@fluentcommerce/ai-skills 0.1.0

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 (60) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +622 -0
  3. package/bin/cli.mjs +1973 -0
  4. package/content/cli/agents/fluent-cli/agent.json +149 -0
  5. package/content/cli/agents/fluent-cli.md +132 -0
  6. package/content/cli/skills/fluent-bootstrap/SKILL.md +181 -0
  7. package/content/cli/skills/fluent-cli-index/SKILL.md +63 -0
  8. package/content/cli/skills/fluent-cli-mcp-cicd/SKILL.md +77 -0
  9. package/content/cli/skills/fluent-cli-reference/SKILL.md +1031 -0
  10. package/content/cli/skills/fluent-cli-retailer/SKILL.md +85 -0
  11. package/content/cli/skills/fluent-cli-settings/SKILL.md +106 -0
  12. package/content/cli/skills/fluent-connect/SKILL.md +886 -0
  13. package/content/cli/skills/fluent-module-deploy/SKILL.md +349 -0
  14. package/content/cli/skills/fluent-profile/SKILL.md +180 -0
  15. package/content/cli/skills/fluent-workflow/SKILL.md +310 -0
  16. package/content/dev/agents/fluent-dev/agent.json +88 -0
  17. package/content/dev/agents/fluent-dev.md +525 -0
  18. package/content/dev/reference-modules/catalog.json +4754 -0
  19. package/content/dev/skills/fluent-build/SKILL.md +192 -0
  20. package/content/dev/skills/fluent-connection-analysis/SKILL.md +386 -0
  21. package/content/dev/skills/fluent-custom-code/SKILL.md +895 -0
  22. package/content/dev/skills/fluent-data-module-scaffold/SKILL.md +714 -0
  23. package/content/dev/skills/fluent-e2e-test/SKILL.md +394 -0
  24. package/content/dev/skills/fluent-event-api/SKILL.md +945 -0
  25. package/content/dev/skills/fluent-feature-explain/SKILL.md +603 -0
  26. package/content/dev/skills/fluent-feature-plan/PLAN_TEMPLATE.md +695 -0
  27. package/content/dev/skills/fluent-feature-plan/SKILL.md +227 -0
  28. package/content/dev/skills/fluent-job-batch/SKILL.md +138 -0
  29. package/content/dev/skills/fluent-mermaid-validate/SKILL.md +86 -0
  30. package/content/dev/skills/fluent-module-scaffold/SKILL.md +1928 -0
  31. package/content/dev/skills/fluent-module-validate/SKILL.md +775 -0
  32. package/content/dev/skills/fluent-pre-deploy-check/SKILL.md +1108 -0
  33. package/content/dev/skills/fluent-retailer-config/SKILL.md +1111 -0
  34. package/content/dev/skills/fluent-rule-scaffold/SKILL.md +385 -0
  35. package/content/dev/skills/fluent-scope-decompose/SKILL.md +1021 -0
  36. package/content/dev/skills/fluent-session-audit-export/SKILL.md +632 -0
  37. package/content/dev/skills/fluent-session-summary/SKILL.md +195 -0
  38. package/content/dev/skills/fluent-settings/SKILL.md +1058 -0
  39. package/content/dev/skills/fluent-source-onboard/SKILL.md +632 -0
  40. package/content/dev/skills/fluent-system-monitoring/SKILL.md +767 -0
  41. package/content/dev/skills/fluent-test-data/SKILL.md +513 -0
  42. package/content/dev/skills/fluent-trace/SKILL.md +1143 -0
  43. package/content/dev/skills/fluent-transition-api/SKILL.md +346 -0
  44. package/content/dev/skills/fluent-version-manage/SKILL.md +744 -0
  45. package/content/dev/skills/fluent-workflow-analyzer/SKILL.md +959 -0
  46. package/content/dev/skills/fluent-workflow-builder/SKILL.md +319 -0
  47. package/content/dev/skills/fluent-workflow-deploy/SKILL.md +267 -0
  48. package/content/mcp-extn/agents/fluent-mcp.md +69 -0
  49. package/content/mcp-extn/skills/fluent-mcp-tools/SKILL.md +461 -0
  50. package/content/mcp-official/agents/fluent-mcp-core.md +91 -0
  51. package/content/mcp-official/skills/fluent-mcp-core/SKILL.md +94 -0
  52. package/content/rfl/agents/fluent-rfl.md +56 -0
  53. package/content/rfl/skills/fluent-rfl-assess/SKILL.md +172 -0
  54. package/docs/CAPABILITY_MAP.md +77 -0
  55. package/docs/CLI_COVERAGE.md +47 -0
  56. package/docs/DEV_WORKFLOW.md +802 -0
  57. package/docs/FLOW_RUN.md +142 -0
  58. package/docs/USE_CASES.md +404 -0
  59. package/metadata.json +156 -0
  60. package/package.json +51 -0
@@ -0,0 +1,142 @@
1
+ # flow-run Command Reference
2
+
3
+ `flow-run` provides a structured execution pipeline for Fluent Commerce diagnostics and optional module deployment.
4
+
5
+ It is designed as a practical first step toward autonomous operations:
6
+
7
+ - run deterministic preflight checks
8
+ - validate local config readiness
9
+ - verify Fluent CLI context and environment access
10
+ - optionally deploy a module with explicit confirmation
11
+ - output a JSON report for auditing and automation
12
+
13
+ ## Behavior Summary
14
+
15
+ By default, `flow-run` performs **read-only diagnostics**.
16
+
17
+ Write operations occur only when both flags are present:
18
+
19
+ - `--deploy`
20
+ - `--yes`
21
+
22
+ ## Prerequisites
23
+
24
+ - Node.js 18+
25
+ - Fluent CLI installed and available on `PATH`
26
+ - active Fluent profile/session configured (or explicit profile provided)
27
+ - optional: `.mcp.json` in the project root if MCP readiness checks are required
28
+
29
+ ## Usage
30
+
31
+ ```bash
32
+ npx @fluentcommerce/ai-skills flow-run [options]
33
+ ```
34
+
35
+ ## Options
36
+
37
+ | Option | Description |
38
+ |---|---|
39
+ | `--profile <name>` | Fluent profile used for module/workflow checks |
40
+ | `--retailer <ref>` | Retailer ref used for workflow checks and deploy |
41
+ | `--module <name-or-path>` | Module package path/name for describe/install |
42
+ | `--config <file>` | Config file to scan for unresolved `[[...]]` placeholders |
43
+ | `--deploy` | Enables `fluent module install` step |
44
+ | `--yes` | Mandatory confirmation with `--deploy` |
45
+ | `--exclude-workflows` | Adds `--exclude workflows` to deploy command |
46
+ | `--force` | Adds `--force` to deploy command |
47
+ | `--report <path>` | Custom JSON report output path |
48
+ | `--official-server-name <n>` | MCP official server key in `.mcp.json` (default `fluent-mcp`) |
49
+ | `--extn-server-name <n>` | MCP extension server key in `.mcp.json` (default `fluent-mcp-extn`) |
50
+ | `--skip-mcp-check` | Skip `.mcp.json` validation |
51
+ | `--help` | Show command help |
52
+
53
+ ## Examples
54
+
55
+ Diagnostics-only run:
56
+
57
+ ```bash
58
+ npx @fluentcommerce/ai-skills flow-run \
59
+ --profile YOUR_PROFILE \
60
+ --retailer YOUR_RETAILER_REF \
61
+ --module dist/your-module.zip \
62
+ --config config/module.config.YOUR_RETAILER_REF.json
63
+ ```
64
+
65
+ Deploy run with explicit confirmation:
66
+
67
+ ```bash
68
+ npx @fluentcommerce/ai-skills flow-run \
69
+ --profile YOUR_PROFILE \
70
+ --retailer YOUR_RETAILER_REF \
71
+ --module dist/your-module.zip \
72
+ --config config/module.config.YOUR_RETAILER_REF.json \
73
+ --deploy \
74
+ --yes
75
+ ```
76
+
77
+ Deploy while protecting workflows:
78
+
79
+ ```bash
80
+ npx @fluentcommerce/ai-skills flow-run \
81
+ --profile YOUR_PROFILE \
82
+ --retailer YOUR_RETAILER_REF \
83
+ --module dist/module.zip \
84
+ --deploy \
85
+ --yes \
86
+ --exclude-workflows
87
+ ```
88
+
89
+ ## What Gets Checked
90
+
91
+ Local checks:
92
+
93
+ - `.mcp.json` presence and server key validation
94
+ - unresolved placeholder detection in MCP env values (`YOUR_*`, `your-*`, `[[...]]`)
95
+ - unresolved placeholder detection in module config (`[[...]]`)
96
+
97
+ Fluent CLI checks:
98
+
99
+ - `fluent --version`
100
+ - `fluent profile active`
101
+ - optional `fluent module describe <module>`
102
+ - optional `fluent module list -p <profile>`
103
+ - optional `fluent workflow list -p <profile> -r <retailer>`
104
+
105
+ Optional deploy checks:
106
+
107
+ - `fluent module install ...`
108
+ - post-deploy module/workflow list verification
109
+
110
+ ## Report Output
111
+
112
+ Default report path:
113
+
114
+ ```text
115
+ ./.fluent-ai-skills/flow-run-report-<timestamp>.json
116
+ ```
117
+
118
+ Each report includes:
119
+
120
+ - command metadata (`cwd`, timestamp, package version, options)
121
+ - check-by-check status (`passed`, `warning`, `failed`, `skipped`)
122
+ - command execution details (exit code, duration, sanitized stdout/stderr)
123
+ - summary totals and overall outcome
124
+ - recommendations
125
+
126
+ ## Exit Behavior
127
+
128
+ - exits `0` when no failing checks remain
129
+ - exits non-zero when any **failed** checks are present
130
+ - warnings do not fail the process
131
+
132
+ ## Current Limits
133
+
134
+ `flow-run` currently orchestrates deterministic CLI and config checks, but it does not yet:
135
+
136
+ - auto-generate/repair workflow JSON or rulesets
137
+ - run MCP GraphQL/event tools directly end-to-end
138
+ - auto-classify root cause from workflowlog/error payloads
139
+ - auto-create version bump commits or publish artifacts
140
+ - execute environment-specific business smoke tests autonomously
141
+
142
+ Use this command as a stable baseline for guarded execution and structured evidence collection.
@@ -0,0 +1,404 @@
1
+ # What Can You Do With Fluent AI Skills?
2
+
3
+ A scenario-based guide to everything your AI assistant can do after installing `@fluentcommerce/ai-skills`. Each scenario shows what to say (natural language or slash command), what happens, and what you get back.
4
+
5
+ > **Prerequisites:** Skills installed (`npx @fluentcommerce/ai-skills install`), MCP servers configured (`mcp-setup --profile YOUR_PROFILE`), and workspace connected (`/fluent-connect`).
6
+
7
+ ---
8
+
9
+ ## Quick Reference: "I want to..."
10
+
11
+ | I want to... | Say this | Skill |
12
+ |---|---|---|
13
+ | Understand how a feature works | "Explain how Home Delivery works" | `/fluent-feature-explain` |
14
+ | Debug why an order is stuck | "Why is order HD-001 stuck in BOOKED?" | `/fluent-trace` |
15
+ | Build a new workflow from scratch | "Build an ORDER::RETURNS workflow" | `/fluent-workflow-builder` |
16
+ | Run an end-to-end test | "Run an E2E test of the HD order flow" | `/fluent-e2e-test` |
17
+ | Check if we're ready for go-live | "Run an RFL assessment" | `/fluent-rfl-assess` |
18
+ | Create test data | "Create a test HD order" | `/fluent-test-data` |
19
+ | Scaffold a new Java rule | "Create a new rule called ValidateReturnWindow" | `/fluent-rule-scaffold` |
20
+ | Deploy a module | "Deploy my extension module to HM_TEST" | `/fluent-module-deploy` |
21
+ | Audit settings | "What settings are missing for ORDER::HD?" | `/fluent-settings` |
22
+ | Monitor event health | "Show me event failure rates for the last hour" | `/fluent-system-monitoring` |
23
+ | Set up a new account | "Bootstrap a new Fluent account" | `/fluent-bootstrap` |
24
+ | Analyze workflow structure | "Analyze ORDER::HD for orphaned rulesets" | `/fluent-workflow-analyzer` |
25
+ | See what actions are available | "What actions can I take on an ORDER in BOOKED status?" | `/fluent-transition-api` |
26
+ | Understand the event model | "How does event routing work in Fluent?" | `/fluent-event-api` |
27
+ | Create a location or network | "Set up a warehouse location for testing" | `/fluent-retailer-config` |
28
+ | Check module health | "What modules are deployed? Are they valid?" | `/fluent-module-validate` |
29
+ | Plan a multi-artifact feature | "Plan the curbside pickup feature" | `/fluent-feature-plan` |
30
+ | Onboard existing source into module format | "Refactor this code into a Fluent module" | `/fluent-source-onboard` |
31
+ | Deploy a workflow to an environment | "Deploy the updated ORDER::HD workflow" | `/fluent-workflow-deploy` |
32
+ | Create a data-only module (no Java) | "Scaffold a data module for locations and settings" | `/fluent-data-module-scaffold` |
33
+
34
+ ---
35
+
36
+ ## Scenario 1: "I just joined the project — help me understand what's built"
37
+
38
+ **Situation:** You're a new developer onboarding onto an existing Fluent Commerce implementation. You need to understand the workflows, rules, and integrations before making changes.
39
+
40
+ **Step 1: Connect to the account**
41
+ ```
42
+ /fluent-connect
43
+ ```
44
+ The wizard discovers your CLI profiles, selects the retailer, downloads all workflows, scans for source code, decompiles any JARs, and reports what's available.
45
+
46
+ **Step 2: Explain the main feature**
47
+ ```
48
+ Explain how the Home Delivery order flow works end-to-end
49
+ ```
50
+ This produces a **Feature Architecture Document** with:
51
+ - State machine diagrams (Mermaid) for every entity (ORDER, FULFILMENT_CHOICE, FULFILMENT)
52
+ - Cross-entity sequence diagram showing event propagation
53
+ - Rules & logic table explaining what each ruleset does
54
+ - Settings dependencies with current values
55
+ - Integration points (webhooks, scheduled events)
56
+ - Analysis confidence levels (HIGH/MEDIUM/LOW per rule)
57
+
58
+ Output saved to `accounts/<PROFILE>/analysis/features/Home_Delivery.md`.
59
+
60
+ **Step 3: Analyze specific workflows**
61
+ ```
62
+ Analyze ORDER::HD for orphaned rulesets and trigger coverage
63
+ ```
64
+ Returns a status graph, event chains, process flow classification, and any structural issues.
65
+
66
+ **Step 4: Understand custom code**
67
+ ```
68
+ Analyze the custom code for this account
69
+ ```
70
+ Scans `accounts/<PROFILE>/SOURCE/`, maps rules to workflow rulesets, generates behavior descriptions, and flags any deployed rules without local source.
71
+
72
+ ---
73
+
74
+ ## Scenario 2: "An order is stuck — help me debug it"
75
+
76
+ **Situation:** A production order `HD-12345` has been in BOOKED status for hours and should have progressed to FULFILLED.
77
+
78
+ **Step 1: Trace the order**
79
+ ```
80
+ Why is order HD-12345 stuck in BOOKED?
81
+ ```
82
+ Runs `event.flowInspect` on the order, analyzing all orchestration events to find:
83
+ - Which events fired and which NO_MATCHed
84
+ - Failed webhook deliveries
85
+ - Rulesets that should have triggered but didn't
86
+ - Timeline of every status change
87
+
88
+ **Step 2: Check available actions**
89
+ ```
90
+ What actions can I take on this order right now?
91
+ ```
92
+ Queries the Transition API for user actions available at the current status — shows event names, required attributes, and button labels.
93
+
94
+ **Step 3: Fire a remediation event**
95
+ ```
96
+ Send a RetryFulfilmentAllocation event to order HD-12345
97
+ ```
98
+ Builds and sends the event (with dry-run preview first), then monitors the result.
99
+
100
+ ---
101
+
102
+ ## Scenario 3: "Build a new workflow for Returns"
103
+
104
+ **Situation:** You need to implement a Return Order flow that doesn't exist yet.
105
+
106
+ **Step 1: Plan the workflow**
107
+ ```
108
+ Build an ORDER::RETURN workflow with states: CREATED, APPROVED, ITEMS_RECEIVED, REFUNDED, COMPLETE, CANCELLED
109
+ ```
110
+ The agent enters **plan mode** — presents:
111
+ - State machine diagram (Mermaid `stateDiagram-v2`)
112
+ - Ruleset inventory (what triggers each transition)
113
+ - Settings dependencies
114
+ - Cross-entity interactions
115
+ - Risk assessment
116
+
117
+ **Waits for your approval** before writing any JSON.
118
+
119
+ **Step 2: Scaffold custom rules**
120
+ ```
121
+ Create a rule called ValidateReturnWindow that checks if the return is within 30 days
122
+ ```
123
+ Generates:
124
+ - Java rule class with Fluent SDK boilerplate
125
+ - Test class skeleton
126
+ - Wires the rule into `module.json`
127
+
128
+ **Step 3: Build and deploy**
129
+ ```
130
+ Build the module and deploy to HM_TEST
131
+ ```
132
+ Runs Maven compile, packages the module ZIP, validates structure, and deploys.
133
+
134
+ **Step 4: Test it**
135
+ ```
136
+ Run an E2E test: create a return order, approve it, receive items, process refund
137
+ ```
138
+ Creates test entities dynamically, fires events at each step, polls for status transitions, and reports pass/fail per step.
139
+
140
+ ---
141
+
142
+ ## Scenario 4: "We're going live next week — are we ready?"
143
+
144
+ **Situation:** Pre-production readiness check before go-live.
145
+
146
+ **Step 1: Run RFL assessment**
147
+ ```
148
+ Run a Ready For Launch assessment
149
+ ```
150
+ Analyzes:
151
+ - All deployed workflows (structure, orphaned rulesets, trigger coverage)
152
+ - Custom rules (code quality, test coverage, GraphQL usage)
153
+ - Settings (missing keys, invalid values)
154
+ - Integration points (webhook configuration)
155
+ - Architecture (entity relationships, cross-workflow dependencies)
156
+
157
+ Produces a scored report with risk ratings and prioritized recommendations.
158
+
159
+ **Step 2: Audit settings**
160
+ ```
161
+ Audit all settings for ORDER::HD — find any gaps
162
+ ```
163
+ Cross-references workflow rule parameters against deployed settings. Flags missing settings, wrong value formats, and cascading scope issues.
164
+
165
+ **Step 3: Check event health**
166
+ ```
167
+ Show me event failure rates and NO_MATCH events for the last 24 hours
168
+ ```
169
+ Queries Prometheus metrics or Event API, runs anomaly detection, and reports:
170
+ - Failure rate (threshold: >5%)
171
+ - NO_MATCH events (any = critical — means workflow gaps)
172
+ - PENDING queue buildup
173
+ - Single-event dominance (possible runaway loops)
174
+
175
+ ---
176
+
177
+ ## Scenario 5: "Set up a fresh environment for testing"
178
+
179
+ **Situation:** You need a clean retailer environment with locations, networks, inventory, and test data.
180
+
181
+ **Step 1: Bootstrap (new account)**
182
+ ```
183
+ Bootstrap a new Fluent account from scratch
184
+ ```
185
+ Walks through: profile creation, retailer setup, reference module installation, sample data.
186
+
187
+ **Or configure an existing retailer:**
188
+ ```
189
+ Set up a warehouse location called "Sydney DC" with 24/7 hours
190
+ ```
191
+ Creates the location via GraphQL with proper `openingSchedule`.
192
+
193
+ **Step 2: Create test data**
194
+ ```
195
+ Create a test HD order with 2 items
196
+ ```
197
+ Auto-discovers available products, locations, and customers from the live environment. Generates a valid order payload — no hardcoded refs.
198
+
199
+ **Step 3: Run smoke test**
200
+ ```
201
+ Run an E2E test of the full HD order flow
202
+ ```
203
+ Creates order → fires events through each status → asserts transitions → reports results. On failure, automatically runs event forensics to show exactly where it broke.
204
+
205
+ ---
206
+
207
+ ## Scenario 6: "Monitor production event processing"
208
+
209
+ **Situation:** Ongoing operational monitoring of event health.
210
+
211
+ **Quick health check:**
212
+ ```
213
+ Run a health check on event processing
214
+ ```
215
+ Single call that checks failure rates, NO_MATCH events, pending queues, and event dominance.
216
+
217
+ **Detailed metrics:**
218
+ ```
219
+ Show me the top 20 events by volume in the last 6 hours
220
+ ```
221
+ Aggregates events by name + entity type + status, ranks by volume, shows failure rates per event.
222
+
223
+ **SLO report:**
224
+ ```
225
+ Generate an SLO report for the last 24 hours
226
+ ```
227
+ Computes event volume, failure/NO_MATCH/pending rates, p95 runtime and inflight latency. Flags any threshold breaches.
228
+
229
+ **Deep dive on failures:**
230
+ ```
231
+ What are the top failing events? Show me details
232
+ ```
233
+ Lists top failing events with counts, then drills into specific failures with `event.flowInspect`.
234
+
235
+ ---
236
+
237
+ ## Scenario 7: "I need to understand the event model"
238
+
239
+ **Situation:** You're new to Fluent's event-driven architecture and need to understand how events work.
240
+
241
+ ```
242
+ How does event routing work in Fluent? What are the event types and statuses?
243
+ ```
244
+ Explains:
245
+ - Event types (ORCHESTRATION, API, ORCHESTRATION_AUDIT)
246
+ - Event categories (GENERAL, ACTION, CUSTOMER)
247
+ - Event statuses (SUCCESS, FAILED, NO_MATCH, PENDING, SCHEDULED)
248
+ - The routing model (how events match to workflow rulesets via triggers)
249
+ - Run-once workflows and scheduled events
250
+ - How to query and filter events for debugging
251
+
252
+ ---
253
+
254
+ ## Scenario 8: "Deploy a workflow change safely"
255
+
256
+ **Situation:** You've modified a workflow and need to deploy it without breaking production.
257
+
258
+ **Step 1: Diff the changes**
259
+ ```
260
+ Compare the current ORDER::HD workflow with my modified version
261
+ ```
262
+ Shows added/removed/modified rulesets, risk assessment (removing rulesets = HIGH risk), and before/after state diagrams.
263
+
264
+ **Step 2: Validate connections**
265
+ ```
266
+ Run connection analysis on ORDER::HD — check for broken cross-entity links
267
+ ```
268
+ Maps all internal, cross-entity, and cross-workflow connections. Flags any rulesets that emit events with no matching triggers.
269
+
270
+ **Step 3: Deploy**
271
+ ```
272
+ Deploy the updated ORDER::HD workflow
273
+ ```
274
+ Uses `/fluent-workflow-deploy` — validates structure, uploads via MCP `workflow.upload` tool (with dry-run first), falls back to REST API if needed, returns new version number.
275
+
276
+ **Step 4: Verify**
277
+ ```
278
+ Run an E2E test of the HD flow to verify the deployment
279
+ ```
280
+ Exercises the deployed workflow end-to-end and reports pass/fail.
281
+
282
+ ---
283
+
284
+ ## Scenario 9: "Batch ingest inventory data"
285
+
286
+ **Situation:** You need to load inventory positions in bulk.
287
+
288
+ ```
289
+ Create a batch ingestion job for inventory positions
290
+ ```
291
+ Walks through: creating the job, sending records in batches, polling status, and checking per-record results.
292
+
293
+ ---
294
+
295
+ ## Scenario 10: "Decompose a scope document into tasks"
296
+
297
+ **Situation:** You have a structured scope document (ADD format) and need an executable task plan.
298
+
299
+ ```
300
+ Decompose this scope document into tasks with dependencies
301
+ ```
302
+ Parses the scope, generates an ordered task list with:
303
+ - Dependency DAG (which tasks block which)
304
+ - Skill mappings (which skill handles each task)
305
+ - Ambiguity flags (where the scope is unclear)
306
+ - SCAFFOLD vs EXTEND vs SOURCE_ONBOARD decisions
307
+
308
+ ---
309
+
310
+ ## Scenario 11: "Onboard existing source into a proper module"
311
+
312
+ **Situation:** You have Java rule classes from another team or a decompiled JAR, but they're not in Fluent Commerce module format. You need a buildable, deployable module.
313
+
314
+ **Step 1: Onboard the source**
315
+ ```
316
+ Refactor this code into a Fluent module: accounts/HMDEV/SOURCE/.decompiled/fc-module-ext/
317
+ ```
318
+ Or for loose Java files:
319
+ ```
320
+ /fluent-source-onboard ./my-rules/ --module-name hm-returns
321
+ ```
322
+
323
+ The skill:
324
+ 1. **Analyzes** the existing layout (decompiled JAR? loose files? Gradle project? partial module?)
325
+ 2. **Discovers** all rule classes (by `@RuleInfo`, `BaseRule` extension, `run()` methods)
326
+ 3. **Plans** the target Maven multi-module structure with a full file operations table
327
+ 4. **Waits for your approval** before changing anything
328
+
329
+ **Step 2: Review the plan**
330
+
331
+ The plan shows exactly what will happen:
332
+ - Which files move where
333
+ - What code changes are needed (package renames, base class fixes, missing annotations)
334
+ - Risk assessment (package renames breaking imports, decompiled artifacts, key conflicts)
335
+
336
+ **Step 3: Execute and validate**
337
+
338
+ After approval:
339
+ - Creates the Maven multi-module directory structure
340
+ - Moves and repackages Java files
341
+ - Fixes structural issues (wrong base class, missing `@RuleInfo`, etc.)
342
+ - Generates `module.json` with all rule registrations
343
+ - Generates build scripts, POMs, `.gitignore`
344
+ - Generates test skeletons for untested rules
345
+ - Runs `/fluent-module-validate` to verify structure
346
+ - Attempts a Maven build to verify compilation
347
+ - Cross-references against deployed rules
348
+
349
+ **Supports these input types:**
350
+ - Decompiled JAR output (`.decompiled/` directories)
351
+ - Loose Java files (no build system)
352
+ - Non-standard Maven projects
353
+ - Gradle projects (converted to Maven)
354
+ - Existing modules with structural issues (repair mode)
355
+
356
+ ---
357
+
358
+ ## What Happens Behind the Scenes
359
+
360
+ When you ask your AI assistant to perform these tasks, it doesn't just generate text — it **executes real operations** against your Fluent environment:
361
+
362
+ | Layer | What it does |
363
+ |-------|-------------|
364
+ | **AI Skills** (knowledge layer) | Teach the AI *how* to do Fluent tasks — patterns, decision trees, best practices |
365
+ | **MCP Extension Server** (execution layer) | 36 tools for real API operations — GraphQL queries, event dispatch, metrics, batch ingestion |
366
+ | **Official MCP Server** (CLI layer) | Workflow listing, downloading, GraphQL validation via the Fluent CLI |
367
+ | **Fluent Commerce API** (platform) | The actual REST/GraphQL endpoints being called |
368
+
369
+ The AI plans its approach, calls the right tools in the right order, handles errors, and reports results — all through natural conversation.
370
+
371
+ ---
372
+
373
+ ## Evidence and Confidence
374
+
375
+ Analysis outputs include confidence levels based on available evidence:
376
+
377
+ | Evidence available | Confidence | What you get |
378
+ |---|---|---|
379
+ | Workflow JSON + `plugin.list` only | LOW-MEDIUM | Structure is accurate; rule behavior is inferred from descriptions |
380
+ | + Decompiled JAR (bytecode) | MEDIUM-HIGH | Implementation logic visible but variable names may be synthetic |
381
+ | + Original source code | HIGH | Full logic, test coverage, and prop validation |
382
+ | + Runtime evidence (real entity trace) | HIGHEST | Static analysis validated against actual execution |
383
+
384
+ When evidence is incomplete, the AI flags it explicitly and recommends how to get higher confidence (provide source, run a test entity, etc.).
385
+
386
+ ---
387
+
388
+ ## Known Limitations
389
+
390
+ | Capability | Status | Workaround |
391
+ |-----------|--------|-----------|
392
+ | Refactor loose source into module format | **Supported** via `/fluent-source-onboard` | Analyzes, plans, restructures, validates, and builds in one flow (see Scenario 11) |
393
+ | Live log tailing / real-time event streaming | Not supported | Use `event.list` with time filters for polling |
394
+ | Multi-retailer operations in single command | Not supported | Switch retailer context between operations |
395
+
396
+ ---
397
+
398
+ ## Further Reading
399
+
400
+ - [README.md](../README.md) — Installation, setup, CLI reference
401
+ - [DEV_WORKFLOW.md](DEV_WORKFLOW.md) — Full development lifecycle with all phases
402
+ - [CAPABILITY_MAP.md](CAPABILITY_MAP.md) — Skill ownership and routing rules
403
+ - [FLOW_RUN.md](FLOW_RUN.md) — Diagnostics and deployment flow details
404
+ - [CLI_COVERAGE.md](CLI_COVERAGE.md) — Fluent CLI command coverage matrix
package/metadata.json ADDED
@@ -0,0 +1,156 @@
1
+ {
2
+ "version": "0.0.1",
3
+ "organization": "Fluent Commerce",
4
+ "date": "February 2026",
5
+ "package": "@fluentcommerce/ai-skills",
6
+ "abstract": "Fluent Commerce skill packs with modular groups for CLI operations, official MCP core, MCP extension tools, Ready For Launch assessments, and development lifecycle automation.",
7
+ "groups": {
8
+ "cli": {
9
+ "name": "Fluent CLI",
10
+ "path": "content/cli",
11
+ "description": "Profile management, module deployment, workflow operations, and account bootstrap",
12
+ "agents": [
13
+ "fluent-cli.md",
14
+ "fluent-cli"
15
+ ],
16
+ "skills": [
17
+ "fluent-cli-reference",
18
+ "fluent-cli-index",
19
+ "fluent-cli-mcp-cicd",
20
+ "fluent-bootstrap",
21
+ "fluent-cli-retailer",
22
+ "fluent-cli-settings",
23
+ "fluent-module-deploy",
24
+ "fluent-profile",
25
+ "fluent-workflow",
26
+ "fluent-connect"
27
+ ],
28
+ "commands": [
29
+ "/fluent-cli-reference",
30
+ "/fluent-cli-index",
31
+ "/fluent-cli-mcp-cicd",
32
+ "/fluent-bootstrap",
33
+ "/fluent-cli-retailer",
34
+ "/fluent-cli-settings",
35
+ "/fluent-module-deploy",
36
+ "/fluent-profile",
37
+ "/fluent-workflow",
38
+ "/fluent-connect"
39
+ ]
40
+ },
41
+ "mcp-official": {
42
+ "name": "Fluent MCP Official",
43
+ "path": "content/mcp-official",
44
+ "description": "Official Fluent CLI MCP server setup, profile context checks, and core MCP diagnostics",
45
+ "agents": [
46
+ "fluent-mcp-core.md"
47
+ ],
48
+ "skills": [
49
+ "fluent-mcp-core"
50
+ ],
51
+ "commands": [
52
+ "/fluent-mcp-core"
53
+ ]
54
+ },
55
+ "mcp-extn": {
56
+ "name": "Fluent MCP Extension",
57
+ "path": "content/mcp-extn",
58
+ "description": "Event dispatch, GraphQL operations, batch ingestion, and webhook validation via MCP extension server",
59
+ "agents": [
60
+ "fluent-mcp.md"
61
+ ],
62
+ "skills": [
63
+ "fluent-mcp-tools"
64
+ ],
65
+ "commands": [
66
+ "/fluent-mcp-tools"
67
+ ]
68
+ },
69
+ "rfl": {
70
+ "name": "Fluent RFL",
71
+ "path": "content/rfl",
72
+ "description": "Ready For Launch assessments - workflow analysis, rules review, configuration audit",
73
+ "agents": [
74
+ "fluent-rfl.md"
75
+ ],
76
+ "skills": [
77
+ "fluent-rfl-assess"
78
+ ],
79
+ "commands": [
80
+ "/fluent-rfl-assess"
81
+ ]
82
+ },
83
+ "dev": {
84
+ "name": "Fluent Dev",
85
+ "path": "content/dev",
86
+ "description": "Development lifecycle - workflow building, custom code analysis, rule scaffolding, module builds, event tracing, and E2E testing",
87
+ "agents": [
88
+ "fluent-dev.md",
89
+ "fluent-dev"
90
+ ],
91
+ "skills": [
92
+ "fluent-workflow-builder",
93
+ "fluent-workflow-analyzer",
94
+ "fluent-workflow-deploy",
95
+ "fluent-custom-code",
96
+ "fluent-transition-api",
97
+ "fluent-rule-scaffold",
98
+ "fluent-module-validate",
99
+ "fluent-module-scaffold",
100
+ "fluent-data-module-scaffold",
101
+ "fluent-build",
102
+ "fluent-trace",
103
+ "fluent-event-api",
104
+ "fluent-system-monitoring",
105
+ "fluent-e2e-test",
106
+ "fluent-test-data",
107
+ "fluent-settings",
108
+ "fluent-retailer-config",
109
+ "fluent-connection-analysis",
110
+ "fluent-job-batch",
111
+ "fluent-session-summary",
112
+ "fluent-scope-decompose",
113
+ "fluent-version-manage",
114
+ "fluent-pre-deploy-check",
115
+ "fluent-session-audit-export",
116
+ "fluent-feature-explain",
117
+ "fluent-feature-plan",
118
+ "fluent-source-onboard",
119
+ "fluent-mermaid-validate"
120
+ ],
121
+ "commands": [
122
+ "/fluent-workflow-builder",
123
+ "/fluent-workflow-analyzer",
124
+ "/fluent-workflow-deploy",
125
+ "/fluent-custom-code",
126
+ "/fluent-transition-api",
127
+ "/fluent-rule-scaffold",
128
+ "/fluent-module-validate",
129
+ "/fluent-module-scaffold",
130
+ "/fluent-data-module-scaffold",
131
+ "/fluent-build",
132
+ "/fluent-trace",
133
+ "/fluent-event-api",
134
+ "/fluent-system-monitoring",
135
+ "/fluent-e2e-test",
136
+ "/fluent-test-data",
137
+ "/fluent-settings",
138
+ "/fluent-retailer-config",
139
+ "/fluent-connection-analysis",
140
+ "/fluent-job-batch",
141
+ "/fluent-session-summary",
142
+ "/fluent-scope-decompose",
143
+ "/fluent-version-manage",
144
+ "/fluent-pre-deploy-check",
145
+ "/fluent-session-audit-export",
146
+ "/fluent-feature-explain",
147
+ "/fluent-feature-plan",
148
+ "/fluent-source-onboard"
149
+ ]
150
+ }
151
+ },
152
+ "references": [
153
+ "https://docs.fluentcommerce.com",
154
+ "https://docs.fluentcommerce.com/docs/cli-overview"
155
+ ]
156
+ }