@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.
- package/LICENSE +21 -0
- package/README.md +622 -0
- package/bin/cli.mjs +1973 -0
- package/content/cli/agents/fluent-cli/agent.json +149 -0
- package/content/cli/agents/fluent-cli.md +132 -0
- package/content/cli/skills/fluent-bootstrap/SKILL.md +181 -0
- package/content/cli/skills/fluent-cli-index/SKILL.md +63 -0
- package/content/cli/skills/fluent-cli-mcp-cicd/SKILL.md +77 -0
- package/content/cli/skills/fluent-cli-reference/SKILL.md +1031 -0
- package/content/cli/skills/fluent-cli-retailer/SKILL.md +85 -0
- package/content/cli/skills/fluent-cli-settings/SKILL.md +106 -0
- package/content/cli/skills/fluent-connect/SKILL.md +886 -0
- package/content/cli/skills/fluent-module-deploy/SKILL.md +349 -0
- package/content/cli/skills/fluent-profile/SKILL.md +180 -0
- package/content/cli/skills/fluent-workflow/SKILL.md +310 -0
- package/content/dev/agents/fluent-dev/agent.json +88 -0
- package/content/dev/agents/fluent-dev.md +525 -0
- package/content/dev/reference-modules/catalog.json +4754 -0
- package/content/dev/skills/fluent-build/SKILL.md +192 -0
- package/content/dev/skills/fluent-connection-analysis/SKILL.md +386 -0
- package/content/dev/skills/fluent-custom-code/SKILL.md +895 -0
- package/content/dev/skills/fluent-data-module-scaffold/SKILL.md +714 -0
- package/content/dev/skills/fluent-e2e-test/SKILL.md +394 -0
- package/content/dev/skills/fluent-event-api/SKILL.md +945 -0
- package/content/dev/skills/fluent-feature-explain/SKILL.md +603 -0
- package/content/dev/skills/fluent-feature-plan/PLAN_TEMPLATE.md +695 -0
- package/content/dev/skills/fluent-feature-plan/SKILL.md +227 -0
- package/content/dev/skills/fluent-job-batch/SKILL.md +138 -0
- package/content/dev/skills/fluent-mermaid-validate/SKILL.md +86 -0
- package/content/dev/skills/fluent-module-scaffold/SKILL.md +1928 -0
- package/content/dev/skills/fluent-module-validate/SKILL.md +775 -0
- package/content/dev/skills/fluent-pre-deploy-check/SKILL.md +1108 -0
- package/content/dev/skills/fluent-retailer-config/SKILL.md +1111 -0
- package/content/dev/skills/fluent-rule-scaffold/SKILL.md +385 -0
- package/content/dev/skills/fluent-scope-decompose/SKILL.md +1021 -0
- package/content/dev/skills/fluent-session-audit-export/SKILL.md +632 -0
- package/content/dev/skills/fluent-session-summary/SKILL.md +195 -0
- package/content/dev/skills/fluent-settings/SKILL.md +1058 -0
- package/content/dev/skills/fluent-source-onboard/SKILL.md +632 -0
- package/content/dev/skills/fluent-system-monitoring/SKILL.md +767 -0
- package/content/dev/skills/fluent-test-data/SKILL.md +513 -0
- package/content/dev/skills/fluent-trace/SKILL.md +1143 -0
- package/content/dev/skills/fluent-transition-api/SKILL.md +346 -0
- package/content/dev/skills/fluent-version-manage/SKILL.md +744 -0
- package/content/dev/skills/fluent-workflow-analyzer/SKILL.md +959 -0
- package/content/dev/skills/fluent-workflow-builder/SKILL.md +319 -0
- package/content/dev/skills/fluent-workflow-deploy/SKILL.md +267 -0
- package/content/mcp-extn/agents/fluent-mcp.md +69 -0
- package/content/mcp-extn/skills/fluent-mcp-tools/SKILL.md +461 -0
- package/content/mcp-official/agents/fluent-mcp-core.md +91 -0
- package/content/mcp-official/skills/fluent-mcp-core/SKILL.md +94 -0
- package/content/rfl/agents/fluent-rfl.md +56 -0
- package/content/rfl/skills/fluent-rfl-assess/SKILL.md +172 -0
- package/docs/CAPABILITY_MAP.md +77 -0
- package/docs/CLI_COVERAGE.md +47 -0
- package/docs/DEV_WORKFLOW.md +802 -0
- package/docs/FLOW_RUN.md +142 -0
- package/docs/USE_CASES.md +404 -0
- package/metadata.json +156 -0
- package/package.json +51 -0
package/docs/FLOW_RUN.md
ADDED
|
@@ -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
|
+
}
|