@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/dev/skills/fluent-workflow-builder/SKILL.md

@@ -1,319 +1,668 @@
----
-name: fluent-workflow-builder
-description: Create and edit Fluent Commerce workflow JSON definitions. Build rulesets, states, transitions, and triggers. Validate structure before upload. Triggers on "build workflow", "create workflow", "add ruleset", "edit workflow", "workflow json".
-user-invocable: true
-allowed-tools: Bash, Read, Write, Edit, Glob, Grep
-argument-hint: <operation> [workflow-name]
----
-
-# Workflow Builder
-
-Create, edit, and validate Fluent Commerce workflow JSON definitions.
-
-## Planning Gate
-
-**Before creating or modifying any workflow, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** Every table row must carry a Source column (NEW/EXISTING/MODIFIED/REUSED/OOTB).
-
-**If this workflow change is part of a larger feature** (rules + settings + webhooks), use `/fluent-feature-plan` first. Then reference the approved plan during implementation.
-
-**Workflow-builder specific emphasis — ensure these are covered:**
-
-1. **Business Context (§1)** — what business flow this workflow enables or modifies
-2. **State machine (§3.1)** — Mermaid `stateDiagram-v2` with ALL statuses; annotate `:::added`, `:::removed`, `:::modified`. Validate syntax per `/fluent-mermaid-validate`
-3. **Cross-entity flow (§3.2)** — Mermaid `sequenceDiagram` for cross-entity event chains, webhooks, external systems. Validate syntax per `/fluent-mermaid-validate`
-4. **Before/After diff (§3.4)** — if modifying, show changes (or use `workflow.diff`)
-5. **Workflows (§4)** — every workflow created or modified with Source column and current version
-6. **Statuses (§5)** — new/modified statuses with Source column, entity type, which ruleset adds them
-7. **Rulesets (§6)** — rulesets with Source column, trigger event, from/to status, ordered rule list with NEW/OOTB/EXISTING annotations
-8. **Rules Inventory (§7)** — all rules with Source classification
-9. **Settings (§9)** — settings with Source column, context, value type, JSON example for NEW
-10. **Webhooks (§10)** — setting name, method, payload shape, trigger rule
-11. **Scheduled Events (§11)** — event name, delay, purpose
-12. **GraphQL Operations (§12)** — queries/mutations marked as NEW or REUSED pattern
-13. **Deployment Sequence (§17)** — modules before workflows that reference new rules
-
-**Write the plan to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-workflow-builder-<slug>.md`. Set `Status: PENDING`.
-
-Present the full plan content to the user and wait for approval before writing any workflow JSON. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
-
-## Ownership Boundary
-
-This skill owns workflow structure/design guidance and validation checklists.
-
-Operational workflow commands are owned by `/fluent-workflow`:
-
-- `workflow list`
-- `workflow download`
-- `workflow merge`
-- `workflowlog` operations
-
-## Pre-Check: Load Source Analysis
-
-Before adding custom rules to a workflow, check if `/fluent-custom-code` analysis artifacts exist:
-
-```
-accounts/<PROFILE>/analysis/custom-code/workflow-rule-map.json
-accounts/<PROFILE>/analysis/custom-code/source-map.json
-accounts/<PROFILE>/analysis/custom-code/constraints.json
-```
-
-If found, use them to:
-- `source-map.json` → `modules[].rules[]` — available custom rules, their parameters, and entity types
-- `workflow-rule-map.json` → existing rule-to-workflow bindings (avoid duplicates)
-- `constraints.json` → extension constraints and risks
-
-If not found, fall back to workflow JSON analysis only. Treat artifact-gate failures the same as "not found" (for example missing required files, missing hashes, or blocking `missingSources` in `constraints.json`). Suggest running `/fluent-custom-code <PROFILE>` first when adding custom rules.
-
-## When to Use
-
-- Creating a new workflow from scratch
-- Adding rulesets or states to an existing workflow
-- Editing triggers, rules, or gate conditions
-- Validating workflow JSON before upload
-- Generating workflow fragments for merge operations
-
-## Workflow JSON Structure
-
-Every Fluent workflow follows this schema:
-
-```json
-{
-  "retailerId": "<retailer-id>",
-  "version": "<semver>",
-  "entityType": "ORDER | FULFILMENT | RETURN_ORDER | ARTICLE | WAVE | ...",
-  "entitySubtype": "<subtype matching workflow name after ::>",
-  "name": "<ENTITY_TYPE>::<SUBTYPE>",
-  "description": "<human-readable description>",
-  "versionComment": "<what changed in this version>",
-  "createdBy": "<retailer-ref>",
-  "rulesets": [ ... ],
-  "statuses": [ ... ]
-}
-```
-
-### Ruleset Structure
-
-```json
-{
-  "name": "<RulesetName>",
-  "description": "[<ENTITY_TYPE>] What this ruleset does",
-  "type": "<ENTITY_TYPE>",
-  "eventType": "NORMAL",
-  "rules": [
-    {
-      "name": "<ACCOUNT>.<MODULE>.<RuleName>",
-      "props": {
-        "key": "value"
-      }
-    }
-  ],
-  "triggers": [
-    { "status": "<STATUS>" }
-  ],
-  "userActions": []
-}
-```
-
-### Trigger Types
-
-Rulesets are triggered by one of:
-
-| Trigger | When it fires |
-|---------|---------------|
-| `{ "status": "CREATED" }` | Entity enters CREATED status (platform CREATE event) |
-| `{ "status": "ON_VALIDATION" }` | Entity enters ON_VALIDATION status |
-| No status trigger | Ruleset is triggered by a named event matching the ruleset name |
-
-**Convention:** If a ruleset has no `status` trigger, it fires when an event with `name` matching the ruleset name arrives. For example, ruleset `ConfirmValidation` fires on event `ConfirmValidation`.
-
-### Statuses Array
-
-```json
-{
-  "statuses": [
-    { "name": "CREATED", "category": "BOOKING", "entityType": "ORDER" },
-    { "name": "ON_VALIDATION", "category": "BOOKING", "entityType": "ORDER" },
-    { "name": "COMPLETE", "category": "DONE", "entityType": "ORDER" }
-  ]
-}
-```
-
-Categories: `BOOKING`, `FULFILMENT`, `DONE`, `PAYMENT`
-
-## Common Rule Patterns
-
-### Core Rules (provided by Fluent platform)
-
-| Rule | Props | Purpose |
-|------|-------|---------|
-| `<ACCOUNT>.core.SetState` | `status` | Transition entity to new status |
-| `<ACCOUNT>.core.SendEvent` | `eventName` | Fire a named event on current entity |
-| `<ACCOUNT>.core.SendEventOnVerifyingEntityStatus` | `eventName`, `statuses` (comma-separated) | Fire event only if entity is in one of the listed statuses |
-| `<ACCOUNT>.core.SendEventOnVerifyingAllFcStatus` | `eventName`, `statuses` (comma-separated) | Gate: fire event when ALL fulfilment choices reach one of the listed statuses |
-| `<ACCOUNT>.core.ScheduleEvent` | `eventName`, `delay` (seconds) | Schedule a delayed event |
-| `<ACCOUNT>.core.IfEventAttributeValueIsEqual` | `eventAttributeName`, `eventAttributeValue`, `eventName` | Conditional: fire event if attribute matches |
-
-### Extension Rules (from custom extension module)
-
-| Rule | Key Props | Purpose |
-|------|-----------|---------|
-| `<ACCOUNT>.<MODULE>.UpdateStatusHistory` | `toStatus` | Track status transition in attribute |
-| `<ACCOUNT>.<MODULE>.SendWebhookWithDynamicAttributes` | `setting` | Send webhook with config from Setting |
-| `<ACCOUNT>.<MODULE>.UpdateEntityFromSetting` | `setting` | Batch-update entity from event data via Setting |
-| `<ACCOUNT>.<MODULE>.CreateFulfilmentFromSourcingLocation` | *(from event attrs)* | Create fulfilment from sourcing data |
-| `<ACCOUNT>.<MODULE>.UpsertAttribute` | `attributeName`, `attributeType`, `attributeValue` | Set entity attribute |
-| `<ACCOUNT>.<MODULE>.UpsertAttributeFromPath` | `jsonpath`, `attributeName`, `attributeType` | Extract value via JSON path and set as attribute |
-
-## Plan Before Building
-
-**Before creating or editing any workflow, present an implementation plan to the user.** The plan should include:
-
-1. **State machine design** — All statuses and transitions, shown as a Mermaid `stateDiagram-v2`
-2. **Ruleset inventory** — Every ruleset with its trigger condition, rules, and purpose
-3. **Settings dependencies** — Any settings referenced by rules (webhook URLs, thresholds, feature flags)
-4. **Custom rule requirements** — Any new Java rules needed (entity type, parameters, behavior)
-5. **Cross-entity interactions** — How this workflow interacts with other entity workflows (e.g., ORDER → FULFILMENT)
-6. **Deployment sequence** — What gets deployed in what order
-
-For workflow edits, additionally show:
-- **Before/after diff** — What rulesets are being added, removed, or modified
-- **Before/after Mermaid diagrams** — Visual comparison of the state machine changes
-- **Risk assessment** — Impact of changes on existing live entities
-
-**Wait for user approval before making any changes to workflow JSON files.**
-
-## Building a New Workflow
-
-### Step 1: Determine entity type and subtype
-
-```
-Workflow name = <ENTITY_TYPE>::<SUBTYPE>
-Example: ORDER::HD, FULFILMENT::DEFAULT, RETURN_ORDER::DEFAULT
-```
-
-### Step 2: Design the state machine
-
-List all statuses and the events/rules that transition between them. Example:
-
-```
-CREATED → [CREATE ruleset] → ON_VALIDATION
-ON_VALIDATION → [ConfirmValidation event] → IN_PROGRESS
-IN_PROGRESS → [ConfirmShipment event] → SHIPPED
-SHIPPED → [ConfirmDelivery event] → COMPLETE
-```
-
-### Step 3: Build each ruleset
-
-For each transition, create a ruleset with:
-1. The rules to execute (in order — rules run sequentially)
-2. A trigger (status trigger for the first ruleset, event-name trigger for the rest)
-
-### Step 4: Add gate rulesets (if needed)
-
-Gates check child entity statuses before advancing parent. Example:
-
-```json
-{
-  "name": "NotifyFCComplete",
-  "description": "Gate: advance order when all FCs reach terminal status",
-  "type": "ORDER",
-  "eventType": "NORMAL",
-  "rules": [
-    {
-      "name": "ACCT.core.SendEventOnVerifyingAllFcStatus",
-      "props": {
-        "eventName": "SourceOrder",
-        "statuses": "ASSIGNED,CANCELLED,ESCALATED"
-      }
-    }
-  ],
-  "triggers": [],
-  "userActions": []
-}
-```
-
-### Step 5: Validate structure
-
-Before uploading, verify:
-- [ ] Every status referenced in triggers exists in the `statuses` array
-- [ ] Every `SetState` target status exists in the `statuses` array
-- [ ] Every `SendEvent` target has a matching ruleset name (or is handled elsewhere)
-- [ ] Rule names follow `<ACCOUNT>.<MODULE>.<RuleName>` format
-- [ ] No duplicate ruleset names
-- [ ] Version is bumped from previous
-
-## Editing an Existing Workflow
-
-### Get current workflow first
-
-Use `/fluent-workflow` for download/list operations, then apply this skill's structure and validation patterns.
-
-### Make changes
-
-Edit the JSON directly. Common operations:
-
-**Add a new ruleset:**
-```json
-{
-  "name": "NewRulesetName",
-  "description": "[ORDER] What it does",
-  "type": "ORDER",
-  "eventType": "NORMAL",
-  "rules": [ ... ],
-  "triggers": [ { "status": "IN_PROGRESS" } ],
-  "userActions": []
-}
-```
-
-**Add a rule to existing ruleset:**
-Find the ruleset in the `rulesets` array, append to its `rules` array.
-
-**Change a gate condition:**
-Find the gate ruleset, update the `statuses` prop value.
-
-### Upload/merge
-
-Use `/fluent-workflow-deploy` for uploading workflows to environments (MCP tool primary, REST API fallback). Use `/fluent-workflow` for listing, downloading, and merging workflows. Use `/fluent-module-deploy` for deploying full module bundles (JAR + settings + workflows together).
-
-**Important:** If the workflow references new custom rules, deploy the module first via `/fluent-module-deploy` before uploading the workflow. Unregistered rules cause NO_MATCH events at runtime.
-
-## Workflow Fragments
-
-Fragments are partial workflow definitions used with `fluent workflow merge`:
-
-```json
-{
-  "name": "my-customization",
-  "description": "Add custom validation step",
-  "rulesets": [
-    {
-      "name": "CustomValidation",
-      "description": "Custom validation ruleset",
-      "type": "ORDER",
-      "eventType": "NORMAL",
-      "rules": [ ... ],
-      "triggers": [ ... ],
-      "userActions": []
-    }
-  ],
-  "statuses": [
-    { "name": "CUSTOM_VALIDATING", "category": "BOOKING", "entityType": "ORDER" }
-  ]
-}
-```
-
-Merge adds the fragment's rulesets and statuses to the base workflow. Use this for modular customizations.
-
-## Validation Checklist
-
-Run through this before uploading any workflow:
-
-1. **JSON syntax** — Valid JSON (no trailing commas, correct brackets)
-2. **Required fields** — `retailerId`, `version`, `entityType`, `entitySubtype`, `name`, `rulesets`
-3. **Status coverage** — Every SetState target exists in `statuses`
-4. **Event coverage** — Every SendEvent target has a matching ruleset (or is expected inbound)
-5. **Trigger consistency** — Only one ruleset per status trigger (avoid conflicts)
-6. **Rule naming** — `<ACCOUNT>.<MODULE>.<RuleName>` format, all referenced rules exist in platform
-7. **Gate logic** — Gate statuses include all terminal states for child entities
-8. **Version bump** — Version is higher than currently deployed version
-9. **Description** — `versionComment` describes what changed
+---
+name: fluent-workflow-builder
+description: Create and edit Fluent Commerce workflow JSON definitions. Build rulesets, states, transitions, and triggers. Validate structure before upload. Triggers on "build workflow", "create workflow", "add ruleset", "edit workflow", "workflow json".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <operation> [workflow-name]
+---
+
+# Workflow Builder
+
+Create, edit, and validate Fluent Commerce workflow JSON definitions.
+
+## Pre-flight: Feedback Check
+
+Before starting, check for past learnings from this skill:
+
+1. Check if `accounts/<PROFILE>/feedback/fluent-workflow-builder.jsonl` exists
+2. If yes, read last 20 records
+3. Filter to: same entity type/subtype if known, FAILURE or USER_CORRECTED outcomes, confidence = CONFIRMED or PROMOTED
+4. Extract top 3 relevant learnings — use as internal "WATCH OUT" guidance during execution
+5. Do NOT show raw feedback to the user — silently adjust approach based on past issues
+
+## Planning Gate
+
+### Pre-flight: Plan Verification
+
+Before proceeding, check for an existing approved plan:
+
+1. **Search** `accounts/<PROFILE>/features/*/status.json` for an entry with `plan: "APPROVED"` that covers this workflow, OR check `accounts/<PROFILE>/tasks/` for a task plan with `Status: APPROVED`
+2. **If multi-artifact work** (workflow + rules + settings): STOP. Invoke `/fluent-feature-plan` first — this skill cannot be used for multi-artifact work without a feature plan
+3. **If approved plan found:** Skip to implementation, referencing the plan's §4 (Workflows), §5 (Statuses), and §6 (Rulesets) sections
+4. **If single-workflow-only work with no plan:** Continue to the Planning Gate below to write a plan for this skill
+
+**Before creating or modifying any workflow, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** Every table row must carry a Source column (NEW/EXISTING/MODIFIED/REUSED/OOTB).
+
+**If this workflow change is part of a larger feature** (rules + settings + webhooks), use `/fluent-feature-plan` first. Then reference the approved plan during implementation.
+
+**Workflow-builder specific emphasis — ensure these are covered:**
+
+1. **Business Context (§1)** — what business flow this workflow enables or modifies
+2. **State machine (§3.1)** — Mermaid `stateDiagram-v2` with ALL statuses; annotate `:::added`, `:::removed`, `:::modified`. Validate syntax per `/fluent-mermaid-validate`
+3. **Cross-entity flow (§3.2)** — Mermaid `sequenceDiagram` for cross-entity event chains, webhooks, external systems. Validate syntax per `/fluent-mermaid-validate`
+4. **Before/After diff (§3.4)** — if modifying, show changes (or use `workflow.diff`)
+5. **Workflows (§4)** — every workflow created or modified with Source column and current version
+6. **Statuses (§5)** — new/modified statuses with Source column, entity type, which ruleset adds them
+7. **Rulesets (§6)** — rulesets with Source column, trigger event, from/to status, ordered rule list with NEW/OOTB/EXISTING annotations
+8. **Rules Inventory (§7)** — all rules with Source classification
+9. **Settings (§9)** — settings with Source column, context, value type, JSON example for NEW
+10. **Webhooks (§10)** — setting name, method, payload shape, trigger rule
+11. **Scheduled Events (§11)** — event name, delay, purpose
+12. **GraphQL Operations (§12)** — queries/mutations marked as NEW or REUSED pattern
+13. **Deployment Sequence (§17)** — modules before workflows that reference new rules
+
+**Write the plan to:** `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-workflow-builder-<slug>.md`. Set `Status: PENDING`.
+
+Present the full plan content to the user and wait for approval before writing any workflow JSON. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
+
+## Post-Build: Workflow Validation
+
+After building or modifying any workflow JSON, **always recommend running `/fluent-workflow-analyzer`** to validate for:
+- Orphaned rulesets (triggers that can never fire)
+- Trigger conflicts (duplicate event+status combinations)
+- Missing rule references (rules not in `plugin.list`)
+- Structural issues (statuses without transitions, unreachable states)
+
+If the user skips this step, `/fluent-pre-deploy-check` will enforce it before deployment. But catching issues early avoids wasted deploy cycles.
+
+## Ownership Boundary
+
+This skill owns workflow structure/design guidance and validation checklists.
+
+Operational workflow commands are owned by `/fluent-workflow`:
+
+- `workflow list`
+- `workflow download`
+- `workflow merge`
+- `workflowlog` operations
+
+## Pre-flight: Custom Rule Availability
+
+Before building or modifying a workflow that references custom rules, verify those rules are deployed:
+
+1. **Identify custom rules** in the plan's §7 (Rules Inventory) — any rule with Source = NEW, MODIFIED, or EXISTING that is NOT `FLUENTRETAIL.*`
+2. **For each custom rule**, query: `plugin.list({ name: "<RuleName>" })`
+3. **If ALL custom rules found:** Proceed — rules are registered and available.
+4. **If ANY custom rule is MISSING:** **STOP.** Inform the user: *"Custom rule `<RuleName>` is not registered. Deploy the module first via `/fluent-build` → `/fluent-module-deploy`, then resume workflow editing."*
+5. **Exception:** If the workflow is being built as part of a feature plan where module deployment comes later (§17 Deployment Sequence), note the dependency and proceed — but add a `DEPLOYMENT_ORDER_WARNING` comment in the plan.
+
+This check prevents deploying workflows that reference unregistered rules, which causes runtime `NO_MATCH` failures.
+
+## Pre-Check: Load Source Analysis
+
+Before adding custom rules to a workflow, check if `/fluent-custom-code` analysis artifacts exist:
+
+```
+accounts/<PROFILE>/analysis/code/workflow-rule-map.json
+accounts/<PROFILE>/analysis/code/source-map.json
+accounts/<PROFILE>/analysis/code/constraints.json
+```
+
+If found, use them to:
+- `source-map.json` → `modules[].rules[]` — available custom rules, their parameters, and entity types
+- `workflow-rule-map.json` → existing rule-to-workflow bindings (avoid duplicates)
+- `constraints.json` → extension constraints and risks
+
+If not found, fall back to workflow JSON analysis only. Treat artifact-gate failures the same as "not found" (for example missing required files, missing hashes, or blocking `missingSources` in `constraints.json`). Suggest running `/fluent-custom-code <PROFILE>` first when adding custom rules.
+
+## Handoff Protocol
+
+### Signals emitted by this skill
+
+| Signal | Condition | Example |
+|--------|-----------|---------|
+| `-> READY: <path>` | Workflow JSON created/modified | `-> READY: accounts/HMDEV/workflows/HM_TEST/ORDER__HD.json` |
+| `-> NEXT: /fluent-<skill>` | Always validate after build | `-> NEXT: /fluent-workflow-analyzer` |
+| `-> BLOCKED: <reason>` | Prerequisite missing | `-> BLOCKED: PREREQ_MISSING — Custom rule CancelOrderRule not registered. Run /fluent-build + /fluent-module-deploy` |
+| `-> SKIP: <reason>` | No workflow changes needed | `-> SKIP: No workflow changes in this feature plan` |
+
+### Error codes
+
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| `PLAN_REQUIRED` | Multi-artifact work attempted without approved plan | Run `/fluent-feature-plan` first |
+| `PREREQ_MISSING` | Custom rules not deployed or source analysis missing | Deploy module first via `/fluent-build` + `/fluent-module-deploy` |
+| `VALIDATION_FAILED` | Workflow JSON structure invalid | Fix JSON structure per validation checklist |
+
+## When to Use
+
+- Creating a new workflow from scratch
+- Adding rulesets or states to an existing workflow
+- Editing triggers, rules, or gate conditions
+- Validating workflow JSON before upload
+- Generating workflow fragments for merge operations
+
+## Progress
+
+Emit this block at each phase transition to show progress:
+
+```
+▸ /fluent-workflow-builder [1/5]
+  ✓ Entity type & subtype    → Design state machine
+  ○ Build rulesets           ○ Add gate rulesets
+  ○ Validate structure
+```
+
+Update the block as each phase completes — mark completed phases with `✓`, the active phase with `→`, and remaining phases with `○`. Replace `[1/5]` with the current phase number.
+
+## Workflow JSON Structure
+
+Every Fluent workflow follows this schema:
+
+```json
+{
+  "retailerId": "<retailer-id>",
+  "version": "<semver>",
+  "entityType": "ORDER | FULFILMENT | RETURN_ORDER | ARTICLE | WAVE | ...",
+  "entitySubtype": "<subtype matching workflow name after ::>",
+  "name": "<ENTITY_TYPE>::<SUBTYPE>",
+  "description": "<human-readable description>",
+  "versionComment": "<what changed in this version>",
+  "createdBy": "<retailer-ref>",
+  "rulesets": [ ... ],
+  "statuses": [ ... ]
+}
+```
+
+### Ruleset Structure
+
+```json
+{
+  "name": "<RulesetName>",
+  "description": "[<ENTITY_TYPE>] What this ruleset does",
+  "type": "<ENTITY_TYPE>",
+  "subtype": "<ENTITY_SUBTYPE>",
+  "eventType": "NORMAL",
+  "rules": [
+    {
+      "name": "<ACCOUNT>.<MODULE>.<RuleName>",
+      "props": {
+        "key": "value"
+      }
+    }
+  ],
+  "triggers": [
+    { "status": "<STATUS>" }
+  ],
+  "userActions": []
+}
+```
+
+### Trigger Types
+
+Rulesets are triggered by one of:
+
+| Trigger | When it fires |
+|---------|---------------|
+| `{ "status": "CREATED" }` | Entity enters CREATED status (platform CREATE event) |
+| `{ "status": "ON_VALIDATION" }` | Entity enters ON_VALIDATION status |
+| No status trigger | Ruleset is triggered by a named event matching the ruleset name |
+
+**Convention:** If a ruleset has no `status` trigger, it fires when an event with `name` matching the ruleset name arrives. For example, ruleset `ConfirmValidation` fires on event `ConfirmValidation`.
+
+### User Actions
+
+User actions link UI buttons to workflow rulesets. When a user clicks the button, an event is sent via `/event/sync` to trigger the ruleset.
+
+**Schema:**
+
+```json
+{
+  "userActions": [
+    {
+      "eventName": "<EventName>",
+      "context": [
+        {
+          "label": "<Button Label>",
+          "type": "PRIMARY",
+          "modules": ["adminconsole"],
+          "confirm": true
+        }
+      ],
+      "attributes": []
+    }
+  ]
+}
+```
+
+**Field reference:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `eventName` | String | No | Event name sent when button is clicked. If omitted, defaults to the **ruleset name**. Strict recommendation: set it explicitly for every user action and keep it aligned with the ruleset name unless intentionally different. |
+| `context` | Array | Yes | Where and how the button appears. At least one entry required. |
+| `context[].label` | String | Yes | Button text shown in the UI |
+| `context[].type` | String | Yes | `"PRIMARY"` (prominent) or `"SECONDARY"` (overflow menu / ellipsis) |
+| `context[].modules` | Array | Yes | Which UI apps show the button: `"adminconsole"` (OMS), `"store"` (Store App), `"servicepoint"` (Service Point), or any custom manifest app name (the suffix after `fc.mystique.manifest.`) |
+| `context[].confirm` | Boolean | Yes | Whether the UI shows a confirmation dialog before sending the event |
+| `attributes` | Array | No | Attributes collected via the confirmation dialog. Empty array if no input needed. |
+
+### Strict User Action Contract (Non-Negotiable)
+
+Use these guardrails to prevent configuration drift and hallucinated schema fields.
+
+1. `userActions` MUST be inside the ruleset object (never at workflow root).
+2. Ruleset MUST include `subtype`, and it MUST match workflow `entitySubtype` for UI actions to appear.
+3. Set `userActions[].eventName` explicitly and keep it equal to the ruleset `name` unless a deliberate alternate routing is required.
+4. Each `context[]` object MUST include: `label`, `type`, `modules`, `confirm`.
+5. `context[].modules` values MUST be valid app names: `adminconsole`, `store`, `servicepoint`, or known custom manifest app suffixes from `fc.mystique.apps`.
+6. `attributes` is optional; when present, each attribute MUST include `name`, `label`, `type`, and `mandatory`.
+7. Do NOT invent undocumented keys (for example: `actionLabel`, `moduleName`, `requiresConfirmation`, `buttonType`).
+8. User actions are sync UI transitions (`/event/sync`). Keep payloads minimal and schema-accurate.
+
+**Attribute schema** (when confirmation collects user input):
+
+```json
+{
+  "attributes": [
+    {
+      "name": "controlValue",
+      "label": "Control Value",
+      "type": "INTEGER",
+      "source": "",
+      "defaultValue": 0,
+      "mandatory": true
+    }
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | String | Attribute key passed in the event payload |
+| `label` | String | Label shown in the confirmation dialog |
+| `type` | String | `STRING`, `INTEGER`, `BOOLEAN`, `FLOAT` |
+| `source` | String | Setting key to populate dropdown options (e.g., `"settings.cancellationReasons"`). Empty string for free-text input. |
+| `defaultValue` | Any | Pre-filled value in the dialog |
+| `mandatory` | Boolean | Whether the field must be filled before confirming |
+
+**Key rules:**
+
+- The ruleset MUST have a `subtype` (matching the workflow's entity subtype) for the user action to display in the UI.
+- `eventName` is optional -- if omitted, the event name defaults to the ruleset name. Set it explicitly only when the event name differs.
+- A ruleset can be both event-triggered AND have user actions (dual classification). For example, `CancelOrder` can be triggered by a user action button AND by an automated event from another ruleset.
+- `modules` values map to Mystique manifest app names. The `fc.mystique.apps` account-level setting controls which apps are available for selection. To add a user action to `fc.mystique.manifest.custom`, use `"custom"` in the modules array.
+- User actions send events via the synchronous endpoint (`/event/sync`), not the async endpoint. This means the UI blocks until the event is processed.
+
+#### User Action Validation Checklist (MANDATORY)
+
+**Before outputting ANY ruleset with `userActions`, run every check. If any fails, fix before presenting.**
+
+| # | Check | Fail = | Common mistake |
+|---|-------|--------|----------------|
+| UA01 | Ruleset has `subtype` matching workflow entity subtype | Button invisible in UI | Forgetting `"subtype": "HD"` — #1 cause of missing buttons |
+| UA02 | `context` is an **array** (not object) | Runtime error | `"context": {...}` instead of `"context": [{...}]` |
+| UA03 | Every context entry has ALL 4 fields: `label`, `type`, `modules`, `confirm` | Invisible / broken | Omitting `confirm` or `modules` |
+| UA04 | `type` is exactly `"PRIMARY"` or `"SECONDARY"` (uppercase) | Button invisible | `"primary"`, `"default"`, `"action"` — none valid |
+| UA05 | `modules` is **non-empty array** of valid app names | Button invisible | Empty `[]` or wrong name |
+| UA06 | Module values: `"adminconsole"` (OMS), `"store"` (Store), `"servicepoint"` (SP), or custom manifest suffix | Wrong app | `"oms"`, `"fluent-oms"`, `"console"` — not valid |
+| UA07 | `confirm` is **boolean** (`true`/`false`), not string | Dialog broken | `"confirm": "true"` |
+| UA08 | If `attributes` has entries, each has `name`, `label`, `type` | Dialog broken | Missing `name` = no key in event payload |
+| UA09 | Attribute `type`: `STRING`, `INTEGER`, `BOOLEAN`, `FLOAT` (uppercase) | Wrong input | `"string"`, `"text"`, `"number"` — not valid |
+| UA10 | Attribute `source`: empty `""` for free-text, `"settings.<key>"` for dropdown | Dropdown empty | Missing `settings.` prefix |
+| UA11 | `userActions` is array at **ruleset top level** | Silently ignored | Inside `props` or `rules` — wrong |
+| UA12 | `eventName` matches ruleset `name` OR explicitly set to different event | Wrong event | Typo sends event no ruleset catches |
+
+**Hard-forbidden patterns (never generate):**
+
+```
+WRONG: "modules": ["oms"]           → RIGHT: "modules": ["adminconsole"]
+WRONG: "modules": ["fluent-store"]  → RIGHT: "modules": ["store"]
+WRONG: "type": "primary"            → RIGHT: "type": "PRIMARY"
+WRONG: "type": "button"             → RIGHT: "type": "PRIMARY" or "SECONDARY"
+WRONG: "confirm": "true"            → RIGHT: "confirm": true
+WRONG: "context": { ... }           → RIGHT: "context": [{ ... }]
+WRONG: attribute "type": "string"   → RIGHT: attribute "type": "STRING"
+WRONG: "source": "cancellationReasons"  → RIGHT: "source": "settings.cancellationReasons"
+WRONG: userActions inside "rules"   → RIGHT: userActions at ruleset top level
+WRONG: ruleset without "subtype"    → RIGHT: always include "subtype" matching workflow
+```
+
+**Post-output verification:** After generating a user action, verify: (1) Does this ruleset have `subtype`? (2) Does `modules` use the correct app name? (3) Is `context` an array with all 4 fields? If any answer is no, fix before presenting.
+
+**Troubleshooting:** When a user action fires, the browser sends a `POST /api/v4.1/event/sync` call. Use browser DevTools (Network tab) to inspect the request payload, bearer token, and response `eventStatus`. The token is the logged-in user's token -- useful for debugging permission issues.
+
+**When to use user actions:**
+- Manual workflow transitions that require human decision (cancel, reject, approve, confirm)
+- Collecting information from the user at transition time (cancellation reason, tracking number)
+- Actions that should appear as buttons in Fluent OMS or Store apps
+
+**When NOT to use:**
+- Automated status transitions -- use `triggers` with status-based firing
+- System-to-system integrations -- use `SendEvent` rules or the async event API
+- Scheduled/delayed actions -- use `ScheduleEvent` rule
+- Transitions that happen without user involvement (e.g., all fulfilments complete → advance order)
+
+**Common user action patterns:**
+
+| Pattern | eventName | modules | confirm | Typical attributes |
+|---------|-----------|---------|---------|-------------------|
+| Cancel order | `CancelOrder` | `["adminconsole"]` | true | cancellationReason (DROPDOWN from settings) |
+| Confirm order | `ConfirmOrder` | `["adminconsole"]` | true | none |
+| Reject fulfilment | `RejectFulfilment` | `["store"]` | true | rejectionReason (DROPDOWN) |
+| Pick item | `PickItem` | `["store"]` | false | none |
+| Pack fulfilment | `PackFulfilment` | `["store"]` | false | none |
+| Dispatch fulfilment | `DispatchFulfilment` | `["store"]` | true | trackingNumber (STRING), carrier (DROPDOWN) |
+| Approve return | `ApproveReturn` | `["adminconsole"]` | true | none |
+
+**Complete example -- Cancel Order with reason collection:**
+
+```json
+{
+  "name": "CancelOrder",
+  "description": "[ORDER] Cancel order from OMS with reason",
+  "type": "ORDER",
+  "subtype": "HD",
+  "eventType": "NORMAL",
+  "rules": [
+    {
+      "name": "<ACCOUNT>.core.SetState",
+      "props": { "status": "CANCELLED" }
+    }
+  ],
+  "triggers": [],
+  "userActions": [
+    {
+      "eventName": "CancelOrder",
+      "context": [
+        {
+          "label": "Cancel Order",
+          "type": "PRIMARY",
+          "modules": ["adminconsole"],
+          "confirm": true
+        }
+      ],
+      "attributes": [
+        {
+          "name": "cancellationReason",
+          "label": "Cancellation Reason",
+          "type": "STRING",
+          "source": "settings.cancellationReasons",
+          "defaultValue": "",
+          "mandatory": true
+        },
+        {
+          "name": "cancellationNote",
+          "label": "Notes",
+          "type": "STRING",
+          "source": "",
+          "defaultValue": "",
+          "mandatory": false
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Verifying user actions after deployment:**
+
+1. Query the Transition API for the entity status where the button should appear:
+   ```
+   workflow.transitions entityType=ORDER subtype=HD status=BOOKED retailerId=2
+   ```
+   Response `userActions[]` should contain the configured action with `eventName`, `context`, and `attributes`.
+
+2. If `userActions` is empty: check `subtype` on the ruleset (most common cause), verify `modules` matches the manifest app name, confirm the entity is in the correct status.
+
+**Strict validation checklist (run before upload):**
+
+1. Confirm each ruleset with `userActions` has `type` + `subtype`, and `subtype` equals workflow `entitySubtype`.
+2. Confirm `userActions[].eventName` is explicitly set and aligns to ruleset `name` (unless intentionally different).
+3. Confirm every `context[].modules` value is valid for the target UI app.
+4. Run `workflow.transitions` twice:
+   - once with `module: "all"` (truth-source view),
+   - once with the target module (visibility check).
+5. Trigger from UI and inspect `POST /api/v4.1/event/sync` in browser DevTools (payload + response `eventStatus`).
+
+### Statuses Array
+
+```json
+{
+  "statuses": [
+    { "name": "CREATED", "category": "BOOKING", "entityType": "ORDER" },
+    { "name": "ON_VALIDATION", "category": "BOOKING", "entityType": "ORDER" },
+    { "name": "COMPLETE", "category": "DONE", "entityType": "ORDER" }
+  ]
+}
+```
+
+Categories: `BOOKING`, `FULFILMENT`, `DONE`, `PAYMENT`
+
+## Common Rule Patterns
+
+### Core Rules (provided by Fluent platform)
+
+| Rule | Props | Purpose |
+|------|-------|---------|
+| `<ACCOUNT>.core.SetState` | `status` | Transition entity to new status |
+| `<ACCOUNT>.core.SendEvent` | `eventName` | Fire a named event on current entity |
+| `<ACCOUNT>.core.SendEventOnVerifyingEntityStatus` | `eventName`, `statuses` (comma-separated) | Fire event only if entity is in one of the listed statuses |
+| `<ACCOUNT>.core.SendEventOnVerifyingAllFcStatus` | `eventName`, `statuses` (comma-separated) | Gate: fire event when ALL fulfilment choices reach one of the listed statuses |
+| `<ACCOUNT>.core.ScheduleEvent` | `eventName`, `delay` (seconds) | Schedule a delayed event |
+| `<ACCOUNT>.core.IfEventAttributeValueIsEqual` | `eventAttributeName`, `eventAttributeValue`, `eventName` | Conditional: fire event if attribute matches |
+
+### Extension Rules (from custom extension module)
+
+| Rule | Key Props | Purpose |
+|------|-----------|---------|
+| `<ACCOUNT>.<MODULE>.UpdateStatusHistory` | `toStatus` | Track status transition in attribute |
+| `<ACCOUNT>.<MODULE>.SendWebhookWithDynamicAttributes` | `setting` | Send webhook with config from Setting |
+| `<ACCOUNT>.<MODULE>.UpdateEntityFromSetting` | `setting` | Batch-update entity from event data via Setting |
+| `<ACCOUNT>.<MODULE>.CreateFulfilmentFromSourcingLocation` | *(from event attrs)* | Create fulfilment from sourcing data |
+| `<ACCOUNT>.<MODULE>.UpsertAttribute` | `attributeName`, `attributeType`, `attributeValue` | Set entity attribute |
+| `<ACCOUNT>.<MODULE>.UpsertAttributeFromPath` | `jsonpath`, `attributeName`, `attributeType` | Extract value via JSON path and set as attribute |
+
+## Plan Before Building
+
+**Before creating or editing any workflow, present an implementation plan to the user.** The plan should include:
+
+1. **State machine design** — All statuses and transitions, shown as a Mermaid `stateDiagram-v2`
+2. **Ruleset inventory** — Every ruleset with its trigger condition, rules, and purpose
+3. **Settings dependencies** — Any settings referenced by rules (webhook URLs, thresholds, feature flags)
+4. **Custom rule requirements** — Any new Java rules needed (entity type, parameters, behavior)
+5. **Cross-entity interactions** — How this workflow interacts with other entity workflows (e.g., ORDER → FULFILMENT)
+6. **Deployment sequence** — What gets deployed in what order
+
+For workflow edits, additionally show:
+- **Before/after diff** — What rulesets are being added, removed, or modified
+- **Before/after Mermaid diagrams** — Visual comparison of the state machine changes
+- **Risk assessment** — Impact of changes on existing live entities
+
+**Wait for user approval before making any changes to workflow JSON files.**
+
+## Building a New Workflow
+
+### Step 1: Determine entity type and subtype
+
+```
+Workflow name = <ENTITY_TYPE>::<SUBTYPE>
+Example: ORDER::HD, FULFILMENT::DEFAULT, RETURN_ORDER::DEFAULT
+```
+
+### Step 2: Design the state machine
+
+List all statuses and the events/rules that transition between them. Example:
+
+```
+CREATED → [CREATE ruleset] → ON_VALIDATION
+ON_VALIDATION → [ConfirmValidation event] → IN_PROGRESS
+IN_PROGRESS → [ConfirmShipment event] → SHIPPED
+SHIPPED → [ConfirmDelivery event] → COMPLETE
+```
+
+### Step 3: Build each ruleset
+
+For each transition, create a ruleset with:
+1. The rules to execute (in order — rules run sequentially)
+2. A trigger (status trigger for the first ruleset, event-name trigger for the rest)
+
+### Step 4: Add gate rulesets (if needed)
+
+Gates check child entity statuses before advancing parent. Example:
+
+```json
+{
+  "name": "NotifyFCComplete",
+  "description": "Gate: advance order when all FCs reach terminal status",
+  "type": "ORDER",
+  "eventType": "NORMAL",
+  "rules": [
+    {
+      "name": "ACCT.core.SendEventOnVerifyingAllFcStatus",
+      "props": {
+        "eventName": "SourceOrder",
+        "statuses": "ASSIGNED,CANCELLED,ESCALATED"
+      }
+    }
+  ],
+  "triggers": [],
+  "userActions": []
+}
+```
+
+### Step 5: Validate structure
+
+Before uploading, verify:
+- [ ] Every status referenced in triggers exists in the `statuses` array
+- [ ] Every `SetState` target status exists in the `statuses` array
+- [ ] Every `SendEvent` target has a matching ruleset name (or is handled elsewhere)
+- [ ] Rule names follow `<ACCOUNT>.<MODULE>.<RuleName>` format
+- [ ] No duplicate ruleset names
+- [ ] Version is bumped from previous
+
+## Editing an Existing Workflow
+
+### Get current workflow first
+
+Use `/fluent-workflow` for download/list operations, then apply this skill's structure and validation patterns.
+
+### Make changes
+
+Edit the JSON directly. Common operations:
+
+**Add a new ruleset:**
+```json
+{
+  "name": "NewRulesetName",
+  "description": "[ORDER] What it does",
+  "type": "ORDER",
+  "eventType": "NORMAL",
+  "rules": [ ... ],
+  "triggers": [ { "status": "IN_PROGRESS" } ],
+  "userActions": []
+}
+```
+
+**Add a rule to existing ruleset:**
+Find the ruleset in the `rulesets` array, append to its `rules` array.
+
+**Change a gate condition:**
+Find the gate ruleset, update the `statuses` prop value.
+
+### Upload/merge
+
+Use `/fluent-workflow-deploy` for uploading workflows to environments (MCP tool primary, REST API fallback). Use `/fluent-workflow` for listing, downloading, and merging workflows. Use `/fluent-module-deploy` for deploying full module bundles (JAR + settings + workflows together).
+
+**Important:** If the workflow references new custom rules, deploy the module first via `/fluent-module-deploy` before uploading the workflow. Unregistered rules cause NO_MATCH events at runtime.
+
+## Workflow Fragments
+
+Fragments are partial workflow definitions used with `fluent workflow merge`:
+
+```json
+{
+  "name": "my-customization",
+  "description": "Add custom validation step",
+  "rulesets": [
+    {
+      "name": "CustomValidation",
+      "description": "Custom validation ruleset",
+      "type": "ORDER",
+      "eventType": "NORMAL",
+      "rules": [ ... ],
+      "triggers": [ ... ],
+      "userActions": []
+    }
+  ],
+  "statuses": [
+    { "name": "CUSTOM_VALIDATING", "category": "BOOKING", "entityType": "ORDER" }
+  ]
+}
+```
+
+Merge adds the fragment's rulesets and statuses to the base workflow. Use this for modular customizations.
+
+## Session Tracking
+
+When invoked, log the following to the session tracking protocol (consumed by `/fluent-session-summary` and `/fluent-session-audit-export`):
+
+**On entry:**
+```json
+{ "skill": "<this-skill-name>", "timestamp": "<ISO-8601>", "arguments": { "<key>": "<value>", "...": "..." } }
+```
+
+**On exit:**
+```json
+{ "skill": "<this-skill-name>", "outcome": "<completed|failed|skipped>", "changesProduced": ["<seq-numbers>"], "toolCallsProduced": ["<seq-numbers>"], "nextRecommended": "<from-handoff-section>" }
+```
+
+All MCP tool calls made during execution should include `"skill": "<this-skill-name>"` in their tracking record for attribution. The `arguments` object should capture the key parameters actually passed (profile, retailer, entity type, etc.) — not a fixed schema. The `nextRecommended` value comes from the Handoff section below.
+
+## Handoff
+
+| Output Artifact | Consumed By | Path |
+|----------------|-------------|------|
+| Workflow JSON file | `/fluent-workflow-analyzer` (validation) | `accounts/<PROFILE>/workflows/<RETAILER_REF>/<ENTITY_TYPE>__<SUBTYPE>.json` |
+| Workflow JSON file | `/fluent-workflow-deploy` (deployment) | `accounts/<PROFILE>/workflows/<RETAILER_REF>/<ENTITY_TYPE>__<SUBTYPE>.json` |
+| Workflow JSON file | `/fluent-pre-deploy-check` (gate check) | `accounts/<PROFILE>/workflows/<RETAILER_REF>/<ENTITY_TYPE>__<SUBTYPE>.json` |
+
+## Error Reporting
+
+Errors from this skill follow the standard format:
+
+| Field | Description |
+|-------|-------------|
+| `phase` | Skill phase where error occurred (e.g., `pre-flight`, `design`, `generation`, `validation`) |
+| `severity` | `CRITICAL` (blocks downstream), `HIGH` (needs fix), `MEDIUM` (advisory), `LOW` (informational) |
+| `message` | Human-readable error description |
+| `resolution` | Suggested fix or downstream skill to invoke |
+
+## Validation Checklist
+
+Run through this before uploading any workflow:
+
+1. **JSON syntax** — Valid JSON (no trailing commas, correct brackets)
+2. **Required fields** — `retailerId`, `version`, `entityType`, `entitySubtype`, `name`, `rulesets`
+3. **Status coverage** — Every SetState target exists in `statuses`
+4. **Event coverage** — Every SendEvent target has a matching ruleset (or is expected inbound)
+5. **Trigger consistency** — Only one ruleset per status trigger (avoid conflicts)
+6. **Rule naming** — `<ACCOUNT>.<MODULE>.<RuleName>` format, all referenced rules exist in platform
+7. **Gate logic** — Gate statuses include all terminal states for child entities
+8. **Version bump** — Version is higher than currently deployed version
+9. **Description** — `versionComment` describes what changed
+
+## Post-Execution: Feedback Capture
+
+After completing this skill (whether success or failure), write a feedback record:
+
+1. **Classify outcome:** `SUCCESS` (clean build), `PARTIAL_SUCCESS` (built after fixing issues), `FAILURE` (could not complete), `BLOCKED` (prereq missing), `USER_CORRECTED` (user overrode approach)
+2. **Build record:** Create a `feedback-record-v1` JSON object with:
+   - `skill`: `"fluent-workflow-builder"`
+   - `feature`: feature slug if working within a feature, null otherwise
+   - `entityType` / `entitySubtype`: from the workflow being built (e.g., `ORDER`, `HD`)
+   - `phases`: trace of each phase (pre-flight, plan, build-rulesets, build-statuses, validate, etc.) with PASS/FAIL/SKIP
+   - `learnings`: any gotchas discovered during execution
+   - `userCorrections`: any corrections the user provided
+3. **Redact secrets:** Strip tokens, passwords, API keys. Keep business identifiers.
+4. **Append** one JSON line to `accounts/<PROFILE>/feedback/fluent-workflow-builder.jsonl`
+5. **Update** `accounts/<PROFILE>/feedback/index.json` counters (create file and directory with `mkdir -p` if missing)
+
+**Skip capture if:** The execution was trivially simple (e.g., user just asked a question about workflows, no actual build/edit happened).
+
+## Known Pitfalls
+<!-- feedback-promoted: managed section, updated by feedback loop -->
+
+_(No promoted learnings yet.)_
+
+<!-- end feedback-promoted -->