@fluentcommerce/ai-skills 0.2.0 → 0.3.0

package/content/dev/skills/fluent-rule-scaffold/SKILL.md

@@ -1,394 +1,515 @@
----
-name: fluent-rule-scaffold
-description: Scaffold new Fluent Commerce Rubix rules. Generates Java class, test class, and wires into module.json. Triggers on "create rule", "new rule", "scaffold rule", "add rule class".
-user-invocable: true
-allowed-tools: Bash, Read, Write, Edit, Glob, Grep
-argument-hint: <rule-name> [--entity-type ORDER|FULFILMENT|...] [--package common|fulfilment|order|...]
----
-
-# Rule Scaffolder
-
-Generate new Fluent Commerce Rubix rule classes with proper structure, annotations, test skeletons, and module wiring.
-
-## Planning Gate
-
-### Pre-flight: Plan Verification
-
-Before proceeding, check for an existing approved plan:
-
-1. **Search** `accounts/<PROFILE>/plans/` for a file with `Status: APPROVED` that covers this rule
-2. **If multi-artifact work** (this rule + workflow changes + 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 §7 (Rules) and §8 (Detailed Design) sections
-4. **If single-rule-only work with no plan:** Continue to the Planning Gate below to write a plan for this skill
-
-**Before scaffolding any rule, 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). For NEW rules, provide full pseudo logic.
-
-**If this rule is part of a larger feature** (multiple rules + workflow changes + settings), use `/fluent-feature-plan` first to produce the comprehensive plan. Then reference the approved plan during scaffolding.
-
-**Rule-scaffold specific emphasis — ensure these are covered:**
-
-1. **Business Context (§1)** — what business need drives this rule; why custom, not OOTB
-2. **State machine (§3.1)** — show the workflow status where this rule fires, with transitions
-3. **Sequence diagram (§3.2)** — data flow: READ, VALIDATE, QUERY, BUILD, MUTATE, LOG. Use Mermaid `sequenceDiagram`. Validate syntax per `/fluent-mermaid-validate`
-4. **Rulesets (§6)** — which rulesets use this rule, trigger event, from/to status
-5. **Rules Inventory (§7)** — this rule classified as NEW with source label
-6. **Detailed Design (§8)** — parameters table, pseudo logic, GraphQL operations
-7. **Settings (§9)** — settings the rule reads, with context, value type, and shape
-8. **GraphQL Operations (§12)** — queries and mutations, marked as NEW or REUSED pattern
-
-**Write the plan to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-rule-scaffold-<slug>.md`. Set `Status: PENDING`.
-
-Present the full plan content to the user and wait for approval before generating any files. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
-
-## When to Use
-
-- Creating a new custom Rubix rule
-- Adding a rule that follows the project's BaseRule pattern
-- Generating boilerplate with proper annotations and logging
-- Wiring a new rule into `module.json`
-
-## Pre-Check: Use OOTB or Build Custom?
-
-Before scaffolding, determine if an out-of-the-box (OOTB) rule already covers the requirement.
-
-### Decision Tree
-
-```
-User asks: "I need a rule that does X"
-│
-├── 1. Check module inventory
-│   Read: accounts/<PROFILE>/analysis/module-validate/module-inventory.json
-│   If missing → run /fluent-module-validate inventory first
-│
-├── 2. Search registered rules for matching capability
-│   Use MCP tool: plugin.list with name filter
-│   Look for rules whose description matches the ask
-│   Check both FLUENTRETAIL.* (platform) and <ACCOUNT>.* (deployed)
-│
-├── 3. Evaluate match
-│   ├── EXACT MATCH → Recommend OOTB rule
-│   │   Tell user: "Use <RuleName> with parameters: ..."
-│   │   Show accepted entity types and parameters
-│   │   No scaffolding needed
-│   │
-│   ├── PARTIAL MATCH → Evaluate gap
-│   │   Small gap (missing one parameter) → Consider extending OOTB
-│   │   Large gap (fundamentally different) → Build custom
-│   │
-│   └── NO MATCH → Build custom rule
-│       Proceed with scaffolding below
-```
-
-### When OOTB Rules Suffice
-
-| Need | OOTB Rule | Why not custom? |
-|------|-----------|----------------|
-| Change entity status | `SendEvent` / `ChangeStateGQL` | Standard lifecycle — no custom logic needed |
-| Send event to another entity | `SendEventToEntity` | Platform handles entity resolution |
-| Forward event conditionally | `ForwardIf*` family (dozens exist) | Many condition checks already built |
-| Update attributes from event | `SetAttributes` / `UpsertAttributes` | Standard attribute operations |
-| Create a fulfilment | `CreateFulfilmentRule` | Standard fulfilment creation |
-
-### When Custom Rules Are Needed
-
-| Need | Why custom? | Real example |
-|------|------------|-------------|
-| Setting-driven dynamic behavior | OOTB rules have fixed parameters, can't read settings for runtime config | `SendWebhookWithDynamicAttributes`, `UpdateEntityFromSetting` |
-| Complex data transformation | Multi-step JSON path extraction + field mapping | `UpsertAttributeFromPath`, `UpdateFulfilmentItemsFromEvent` |
-| Cross-entity composition | Query one entity to create/update another atomically | `CreateFulfilmentFromSourcingLocation` |
-| Domain-specific validation | Business logic not covered by generic conditions | `CreateMissingVariantProducts` |
-
-### Rule Discovery via MCP
-
-```
-# Search all registered rules by keyword
-plugin.list name="Fulfilment"     → all fulfilment-related rules
-plugin.list name="SendEvent"      → all event-forwarding rules
-plugin.list name="Attribute"      → all attribute manipulation rules
-plugin.list name="Webhook"        → webhook-related rules
-```
-
-Each result includes `description`, `parameters[]`, and `accepts[]` (entity types) — enough to determine fit.
-
-## Rubix Rule Framework
-
-All custom rules in this project follow this architecture:
-
-```
-BaseRule (abstract)
-  └── extends Rule (Rubix SDK)
-  └── wraps Context in ContextWrapper
-  └── provides automatic logging via CommonUtils.generateLog()
-  └── subclasses implement: run(ContextWrapper context)
-```
-
-### Required Annotations
-
-```java
-@RuleInfo(
-    name = "MyRuleName",
-    description = "What this rule does in one sentence"
-)
-@ParamString(name = "paramName", description = "What this parameter controls")
-@Slf4j  // Lombok logging
-public class MyRuleName extends BaseRule {
-    @Override
-    public void run(ContextWrapper context) {
-        // Rule implementation
-    }
-}
-```
-
-### Key APIs
-
-| API | Usage |
-|-----|-------|
-| `context.getProp("name")` | Read ruleset prop value |
-| `context.getEvent()` | Get the triggering event |
-| `context.getEvent().getAccountId()` | Account ID for logging |
-| `context.getEvent().getEntityId()` | Entity ID |
-| `context.getEvent().getEntityRef()` | Entity reference |
-| `context.getEvent().getEntityType()` | Entity type |
-| `context.getEvent().getAttributes()` | Event attributes map |
-| `context.addLog("message")` | Add to execution log |
-| `context.action().mutation()` | Queue a GraphQL mutation (executes AFTER rule completes) |
-| `context.action().eventAction()` | Queue an event to fire |
-| `DynamicUtils.query(context, paths, queryName, params)` | Execute dynamic GraphQL query |
-| `DynamicUtils.mutate(context, values)` | Execute dynamic mutation |
-| `DynamicUtils.getJsonPath(context, jsonPath)` | Resolve value from event or entity |
-| `SettingUtils.getSettingByRef(context, ref)` | Read a Fluent Setting |
-
-## Rule Class Template
-
-```java
-package com.fluentcommerce.rule.<PACKAGE>;
-
-import com.fluentcommerce.common.BaseRule;
-import com.fluentcommerce.common.ContextWrapper;
-import com.fluentretail.rubix.rule.meta.ParamString;
-import com.fluentretail.rubix.rule.meta.RuleInfo;
-import lombok.extern.slf4j.Slf4j;
-
-/**
- * <DESCRIPTION>
- */
-@RuleInfo(
-    name = "<RULE_NAME>",
-    description = "<DESCRIPTION>"
-)
-@ParamString(name = "<PARAM1>", description = "<PARAM1_DESC>")
-@Slf4j
-public class <RULE_NAME> extends BaseRule {
-
-    private static final String CLASS_NAME = <RULE_NAME>.class.getSimpleName();
-
-    @Override
-    public void run(ContextWrapper context) {
-        String accountId = context.getEvent().getAccountId();
-
-        log.info("[{}] [{}] - Processing event: {}", accountId, CLASS_NAME,
-                context.getEvent().getName());
-        context.addLog("Processing " + CLASS_NAME);
-
-        // Read props
-        String param1 = context.getProp("<PARAM1>");
-        if (param1 == null || param1.trim().isEmpty()) {
-            log.error("[{}] [{}] - Required prop '<PARAM1>' is missing", accountId, CLASS_NAME);
-            context.addLog("Error: <PARAM1> is required");
-            return;
-        }
-
-        try {
-            // === Rule logic here ===
-
-            context.addLog(CLASS_NAME + " completed successfully");
-        } catch (Exception e) {
-            log.error("[{}] [{}] - Error: {}", accountId, CLASS_NAME, e.getMessage(), e);
-            context.addLog("Error in " + CLASS_NAME + ": " + e.getMessage());
-        }
-    }
-}
-```
-
-## Test Class Template
-
-```java
-package com.fluentcommerce.rule.<PACKAGE>;
-
-import com.fluentretail.rubix.event.Event;
-import com.fluentretail.rubix.rule.meta.RuleInfo;
-import com.fluentretail.rubix.v2.context.Context;
-import com.fluentretail.rubix.v2.action.Action;
-import com.fluentretail.rubix.v2.action.MutationAction;
-import com.fluentretail.rubix.v2.action.EventAction;
-import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Test;
-import org.junit.jupiter.api.DisplayName;
-import org.mockito.Mock;
-import org.mockito.MockitoAnnotations;
-
-import java.util.HashMap;
-import java.util.Map;
-
-import static org.junit.jupiter.api.Assertions.*;
-import static org.mockito.Mockito.*;
-
-class <RULE_NAME>Test {
-
-    private <RULE_NAME> rule;
-
-    @Mock private Context context;
-    @Mock private Event event;
-    @Mock private Action action;
-    @Mock private MutationAction mutationAction;
-    @Mock private EventAction eventAction;
-
-    @BeforeEach
-    void setUp() {
-        MockitoAnnotations.openMocks(this);
-        rule = new <RULE_NAME>();
-
-        when(context.getEvent()).thenReturn(event);
-        when(context.action()).thenReturn(action);
-        when(action.mutation()).thenReturn(mutationAction);
-        when(action.eventAction()).thenReturn(eventAction);
-        when(event.getAccountId()).thenReturn("TEST_ACCOUNT");
-        when(event.getName()).thenReturn("TestEvent");
-    }
-
-    @Test
-    @DisplayName("Rule has correct @RuleInfo annotation")
-    void hasRuleInfo() {
-        RuleInfo info = <RULE_NAME>.class.getAnnotation(RuleInfo.class);
-        assertNotNull(info);
-        assertEquals("<RULE_NAME>", info.name());
-    }
-
-    @Test
-    @DisplayName("Handles missing required prop gracefully")
-    void missingRequiredProp() {
-        Map<String, String> props = new HashMap<>();
-        when(context.getProp("<PARAM1>")).thenReturn(null);
-
-        // Should not throw — rule logs error and returns
-        assertDoesNotThrow(() -> rule.run(context));
-    }
-
-    @Test
-    @DisplayName("Processes event successfully with valid props")
-    void processesSuccessfully() {
-        when(context.getProp("<PARAM1>")).thenReturn("testValue");
-
-        rule.run(context);
-
-        // Verify expected behavior
-        // verify(mutationAction).xxx(...);
-    }
-}
-```
-
-## Pre-Check: Load Source Analysis
-
-Before scaffolding, check if `/fluent-custom-code` analysis artifacts exist:
-
-```
-accounts/<PROFILE>/analysis/custom-code/source-map.json
-accounts/<PROFILE>/analysis/custom-code/constraints.json
-```
-
-If found, read them to discover:
-- `modules[].patterns.basePackage` — correct package prefix
-- `modules[].patterns.subPackages` — available sub-packages
-- `modules[].patterns.baseClass` — base class to extend
-- `modules[].buildRoot` — where to run Maven
-- `modules[].rules[]` — existing rules (avoid name collisions)
-- `constraints[].extensionConstraints` — rules to follow
-
-If not found, suggest running `/fluent-custom-code <PROFILE>` first, or fall back to the defaults below. Treat artifact-gate failures as "not found" (for example missing required files, missing hashes, or blocking `missingSources` in `constraints.json`).
-
-## Scaffolding Steps
-
-### 1. Determine rule location
-
-Rules live under the plugin source tree:
-
-```
-plugins/rules/<module-alias>/src/main/java/com/fluentcommerce/rule/
-├── common/           # Entity-agnostic rules
-├── fulfilment/       # Fulfilment-specific rules
-├── variantproduct/   # Product-specific rules
-├── order/            # Order-specific rules (create if needed)
-└── returnorder/      # Return order rules (create if needed)
-```
-
-### 2. Create the rule class
-
-Write the Java file at the appropriate package path using the template above. Replace all `<PLACEHOLDERS>`.
-
-### 3. Create the test class
-
-Write the test at the mirror path under `src/test/java/`. Test class name = `<RuleName>Test.java`.
-
-### 4. Wire into module.json
-
-Add the rule name to the `rules` array in the module's `resources/module.json`:
-
-```json
-{
-  "rules": [
-    "ExistingRule1",
-    "ExistingRule2",
-    "NewRuleName"
-  ]
-}
-```
-
-### 5. Verify compilation
-
-```bash
-cd plugins/ && mvn clean install -pl rules/<module-alias> -am
-```
-
-If Maven fails, check:
-- Node.js version (must be 18 for Apollo codegen): `nvm use 18` on Unix; on Windows with nvm-windows (nvm4w), use the full version number: `nvm use 18.x.x`
-- Import paths are correct
-- `BaseRule` and `ContextWrapper` are in the `common` package
-
-## Rules That Use Dynamic GraphQL
-
-For rules that need to query or mutate entities dynamically:
-
-```java
-import com.fluentcommerce.util.dynamic.DynamicUtils;
-
-// Query entity fields via JSON paths
-List<String> paths = Arrays.asList("ref", "status", "fulfilments.ref", "fulfilments.status");
-JsonNode result = DynamicUtils.query(context, paths, "orderQuery", null);
-
-// Mutate entity
-Map<String, Object> values = new HashMap<>();
-values.put("id", entityId);
-values.put("status", "NEW_STATUS");
-values.put("attributes", attributeList);
-DynamicUtils.mutate(context, values);
-```
-
-**Path syntax:** Omit `edges` and `node` — DynamicEntityQuery adds them automatically. Use `items.product.name` not `items.edges.node.product.name`.
-
-## Rules That Read Settings
-
-```java
-import com.fluentcommerce.util.SettingUtils;
-import com.fluentretail.rubix.foundation.graphql.type.Setting;
-
-Setting setting = SettingUtils.getSettingByRef(context, "my.setting.ref");
-JsonNode config = JsonUtils.stringToPojo(setting.getLobValue(), JsonNode.class);
-```
-
-## Gotchas
-
-- **`@ParamString` names are CASE-SENSITIVE** — `"jsonpath"` and `"jsonPath"` are different props
-- **`context.action().mutation()` only QUEUES** — the mutation executes AFTER the rule returns
-- **`DynamicMutation.buildMutationDocument` appends `!`** — never include `!` in type names
-- **`updateFulfilmentItem` does NOT exist** — use `updateFulfilment` with nested `items` array
-- **BaseRule wraps Context** — implement `run(ContextWrapper context)`, not `run(Context context)`
+---
+name: fluent-rule-scaffold
+description: Scaffold new Fluent Commerce Rubix rules. Generates Java class, test class, and wires into module.json. Triggers on "create rule", "new rule", "scaffold rule", "add rule class".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <rule-name> [--entity-type ORDER|FULFILMENT|...] [--package common|fulfilment|order|...]
+---
+
+# Rule Scaffolder
+
+Generate new Fluent Commerce Rubix rule classes with proper structure, annotations, test skeletons, and module wiring.
+
+## Pre-flight: Feedback Check
+
+Before starting, check for past learnings from this skill:
+
+1. Check if `accounts/<PROFILE>/feedback/fluent-rule-scaffold.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 rule, OR check `accounts/<PROFILE>/tasks/` for a task plan with `Status: APPROVED`
+2. **If multi-artifact work** (this rule + workflow changes + 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 §7 (Rules) and §8 (Detailed Design) sections
+4. **If single-rule-only work with no plan:** Continue to the Planning Gate below to write a plan for this skill
+
+**Before scaffolding any rule, 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). For NEW rules, provide full pseudo logic.
+
+**If this rule is part of a larger feature** (multiple rules + workflow changes + settings), use `/fluent-feature-plan` first to produce the comprehensive plan. Then reference the approved plan during scaffolding.
+
+**Rule-scaffold specific emphasis — ensure these are covered:**
+
+1. **Business Context (§1)** — what business need drives this rule; why custom, not OOTB
+2. **State machine (§3.1)** — show the workflow status where this rule fires, with transitions
+3. **Sequence diagram (§3.2)** — data flow: READ, VALIDATE, QUERY, BUILD, MUTATE, LOG. Use Mermaid `sequenceDiagram`. Validate syntax per `/fluent-mermaid-validate`
+4. **Rulesets (§6)** — which rulesets use this rule, trigger event, from/to status
+5. **Rules Inventory (§7)** — this rule classified as NEW with source label
+6. **Detailed Design (§8)** — parameters table, pseudo logic, GraphQL operations
+7. **Settings (§9)** — settings the rule reads, with context, value type, and shape
+8. **GraphQL Operations (§12)** — queries and mutations, marked as NEW or REUSED pattern
+
+**Write the plan to:** `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-rule-scaffold-<slug>.md`. Set `Status: PENDING`.
+
+Present the full plan content to the user and wait for approval before generating any files. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
+
+## Handoff Protocol
+
+### Signals emitted by this skill
+
+| Signal | Condition | Example |
+|--------|-----------|---------|
+| `-> READY: <path>` | Rule class + test scaffolded | `-> READY: accounts/HMDEV/SOURCE/.../CancelOrderRule.java` |
+| `-> NEXT: /fluent-<skill>` | Next skill in chain | `-> NEXT: /fluent-build` |
+| `-> BLOCKED: <reason>` | Prerequisite missing | `-> BLOCKED: PREREQ_MISSING — No module in SOURCE/. Run /fluent-module-scaffold` |
+| `-> SKIP: <reason>` | Rule already exists | `-> SKIP: Rule CancelOrderRule already registered in module.json` |
+
+### Error codes
+
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| `PLAN_REQUIRED` | Multi-artifact work attempted without approved plan | Run `/fluent-feature-plan` first |
+| `PREREQ_MISSING` | No module found in `accounts/<PROFILE>/SOURCE/` | Run `/fluent-module-scaffold` or clone repo |
+| `VALIDATION_FAILED` | Rule name conflicts or entity type mismatch | Fix input parameters and retry |
+
+## When to Use
+
+- Creating a new custom Rubix rule
+- Adding a rule that follows the project's BaseRule pattern
+- Generating boilerplate with proper annotations and logging
+- Wiring a new rule into `module.json`
+
+## Pre-flight: Module Existence
+
+Before scaffolding any rule, verify a target module exists:
+
+1. **Search** `accounts/<PROFILE>/SOURCE/` recursively for `module.json` files
+2. **If module found:** Confirm the module's entity types cover this rule's entity type. Note the module path for downstream scaffolding.
+3. **If NO module found:** **STOP.** Do not scaffold. Inform the user: *"No module found in `accounts/<PROFILE>/SOURCE/`. Run `/fluent-module-scaffold` first to create one, or clone an existing repo into `SOURCE/`."*
+4. **If module found but source-map.json is missing or stale:** Run `/fluent-custom-code` to analyze the module before adding new rules. This ensures package conventions, base class patterns, and existing rule names are known.
+
+This check prevents scaffolding a rule with nowhere to put it.
+
+## Pre-Check: Use OOTB or Build Custom?
+
+Before scaffolding, determine if an out-of-the-box (OOTB) rule already covers the requirement.
+
+### Decision Tree
+
+```
+User asks: "I need a rule that does X"
+│
+├── 1. Check module inventory
+│   Read: accounts/<PROFILE>/analysis/modules/module-inventory.json
+│   If missing → run /fluent-module-validate inventory first
+│
+├── 2. Search registered rules for matching capability
+│   Use MCP tool: plugin.list with name filter
+│   Look for rules whose description matches the ask
+│   Check both FLUENTRETAIL.* (platform) and <ACCOUNT>.* (deployed)
+│
+├── 3. Evaluate match
+│   ├── EXACT MATCH → Recommend OOTB rule
+│   │   Tell user: "Use <RuleName> with parameters: ..."
+│   │   Show accepted entity types and parameters
+│   │   No scaffolding needed
+│   │
+│   ├── PARTIAL MATCH → Evaluate gap
+│   │   Small gap (missing one parameter) → Consider extending OOTB
+│   │   Large gap (fundamentally different) → Build custom
+│   │
+│   └── NO MATCH → Build custom rule
+│       Proceed with scaffolding below
+```
+
+### When OOTB Rules Suffice
+
+| Need | OOTB Rule | Why not custom? |
+|------|-----------|----------------|
+| Change entity status | `SendEvent` / `ChangeStateGQL` | Standard lifecycle — no custom logic needed |
+| Send event to another entity | `SendEventToEntity` | Platform handles entity resolution |
+| Forward event conditionally | `ForwardIf*` family (dozens exist) | Many condition checks already built |
+| Update attributes from event | `SetAttributes` / `UpsertAttributes` | Standard attribute operations |
+| Create a fulfilment | `CreateFulfilmentRule` | Standard fulfilment creation |
+
+### When Custom Rules Are Needed
+
+| Need | Why custom? | Real example |
+|------|------------|-------------|
+| Setting-driven dynamic behavior | OOTB rules have fixed parameters, can't read settings for runtime config | `SendWebhookWithDynamicAttributes`, `UpdateEntityFromSetting` |
+| Complex data transformation | Multi-step JSON path extraction + field mapping | `UpsertAttributeFromPath`, `UpdateFulfilmentItemsFromEvent` |
+| Cross-entity composition | Query one entity to create/update another atomically | `CreateFulfilmentFromSourcingLocation` |
+| Domain-specific validation | Business logic not covered by generic conditions | `CreateMissingVariantProducts` |
+
+### Rule Discovery via MCP
+
+```
+# Search all registered rules by keyword
+plugin.list name="Fulfilment"     → all fulfilment-related rules
+plugin.list name="SendEvent"      → all event-forwarding rules
+plugin.list name="Attribute"      → all attribute manipulation rules
+plugin.list name="Webhook"        → webhook-related rules
+```
+
+Each result includes `description`, `parameters[]`, and `accepts[]` (entity types) — enough to determine fit.
+
+## Rubix Rule Framework
+
+All custom rules in this project follow this architecture:
+
+```
+BaseRule (abstract)
+  └── extends Rule (Rubix SDK)
+  └── wraps Context in ContextWrapper
+  └── provides automatic logging via CommonUtils.generateLog()
+  └── subclasses implement: run(ContextWrapper context)
+```
+
+### Required Annotations
+
+```java
+@RuleInfo(
+    name = "MyRuleName",
+    description = "What this rule does in one sentence"
+)
+@ParamString(name = "paramName", description = "What this parameter controls")
+@Slf4j  // Lombok logging
+public class MyRuleName extends BaseRule {
+    @Override
+    public void run(ContextWrapper context) {
+        // Rule implementation
+    }
+}
+```
+
+### Key APIs
+
+| API | Usage |
+|-----|-------|
+| `context.getProp("name")` | Read ruleset prop value |
+| `context.getEvent()` | Get the triggering event |
+| `context.getEvent().getAccountId()` | Account ID for logging |
+| `context.getEvent().getEntityId()` | Entity ID |
+| `context.getEvent().getEntityRef()` | Entity reference |
+| `context.getEvent().getEntityType()` | Entity type |
+| `context.getEvent().getAttributes()` | Event attributes map |
+| `context.addLog("message")` | Add to execution log |
+| `context.action().mutation()` | Queue a GraphQL mutation (executes AFTER rule completes) |
+| `context.action().eventAction()` | Queue an event to fire |
+| `DynamicUtils.query(context, paths, queryName, params)` | Execute dynamic GraphQL query |
+| `DynamicUtils.mutate(context, values)` | Execute dynamic mutation |
+| `DynamicUtils.getJsonPath(context, jsonPath)` | Resolve value from event or entity |
+| `SettingUtils.getSettingByRef(context, ref)` | Read a Fluent Setting |
+
+## Rule Class Template
+
+```java
+package com.fluentcommerce.rule.<PACKAGE>;
+
+import com.fluentcommerce.common.BaseRule;
+import com.fluentcommerce.common.ContextWrapper;
+import com.fluentretail.rubix.rule.meta.ParamString;
+import com.fluentretail.rubix.rule.meta.RuleInfo;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * <DESCRIPTION>
+ */
+@RuleInfo(
+    name = "<RULE_NAME>",
+    description = "<DESCRIPTION>"
+)
+@ParamString(name = "<PARAM1>", description = "<PARAM1_DESC>")
+@Slf4j
+public class <RULE_NAME> extends BaseRule {
+
+    private static final String CLASS_NAME = <RULE_NAME>.class.getSimpleName();
+
+    @Override
+    public void run(ContextWrapper context) {
+        String accountId = context.getEvent().getAccountId();
+
+        log.info("[{}] [{}] - Processing event: {}", accountId, CLASS_NAME,
+                context.getEvent().getName());
+        context.addLog("Processing " + CLASS_NAME);
+
+        // Read props
+        String param1 = context.getProp("<PARAM1>");
+        if (param1 == null || param1.trim().isEmpty()) {
+            log.error("[{}] [{}] - Required prop '<PARAM1>' is missing", accountId, CLASS_NAME);
+            context.addLog("Error: <PARAM1> is required");
+            return;
+        }
+
+        try {
+            // === Rule logic here ===
+
+            context.addLog(CLASS_NAME + " completed successfully");
+        } catch (Exception e) {
+            log.error("[{}] [{}] - Error: {}", accountId, CLASS_NAME, e.getMessage(), e);
+            context.addLog("Error in " + CLASS_NAME + ": " + e.getMessage());
+        }
+    }
+}
+```
+
+## Test Class Template
+
+```java
+package com.fluentcommerce.rule.<PACKAGE>;
+
+import com.fluentretail.rubix.event.Event;
+import com.fluentretail.rubix.rule.meta.RuleInfo;
+import com.fluentretail.rubix.v2.context.Context;
+import com.fluentretail.rubix.v2.action.Action;
+import com.fluentretail.rubix.v2.action.MutationAction;
+import com.fluentretail.rubix.v2.action.EventAction;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.DisplayName;
+import org.mockito.Mock;
+import org.mockito.MockitoAnnotations;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.Mockito.*;
+
+class <RULE_NAME>Test {
+
+    private <RULE_NAME> rule;
+
+    @Mock private Context context;
+    @Mock private Event event;
+    @Mock private Action action;
+    @Mock private MutationAction mutationAction;
+    @Mock private EventAction eventAction;
+
+    @BeforeEach
+    void setUp() {
+        MockitoAnnotations.openMocks(this);
+        rule = new <RULE_NAME>();
+
+        when(context.getEvent()).thenReturn(event);
+        when(context.action()).thenReturn(action);
+        when(action.mutation()).thenReturn(mutationAction);
+        when(action.eventAction()).thenReturn(eventAction);
+        when(event.getAccountId()).thenReturn("TEST_ACCOUNT");
+        when(event.getName()).thenReturn("TestEvent");
+    }
+
+    @Test
+    @DisplayName("Rule has correct @RuleInfo annotation")
+    void hasRuleInfo() {
+        RuleInfo info = <RULE_NAME>.class.getAnnotation(RuleInfo.class);
+        assertNotNull(info);
+        assertEquals("<RULE_NAME>", info.name());
+    }
+
+    @Test
+    @DisplayName("Handles missing required prop gracefully")
+    void missingRequiredProp() {
+        Map<String, String> props = new HashMap<>();
+        when(context.getProp("<PARAM1>")).thenReturn(null);
+
+        // Should not throw — rule logs error and returns
+        assertDoesNotThrow(() -> rule.run(context));
+    }
+
+    @Test
+    @DisplayName("Processes event successfully with valid props")
+    void processesSuccessfully() {
+        when(context.getProp("<PARAM1>")).thenReturn("testValue");
+
+        rule.run(context);
+
+        // Verify expected behavior
+        // verify(mutationAction).xxx(...);
+    }
+}
+```
+
+## Pre-Check: Load Source Analysis
+
+Before scaffolding, check if `/fluent-custom-code` analysis artifacts exist:
+
+```
+accounts/<PROFILE>/analysis/code/source-map.json
+accounts/<PROFILE>/analysis/code/constraints.json
+```
+
+If found, read them to discover:
+- `modules[].patterns.basePackage` — correct package prefix
+- `modules[].patterns.subPackages` — available sub-packages
+- `modules[].patterns.baseClass` — base class to extend
+- `modules[].buildRoot` — where to run Maven
+- `modules[].rules[]` — existing rules (avoid name collisions)
+- `constraints[].extensionConstraints` — rules to follow
+
+If not found, suggest running `/fluent-custom-code <PROFILE>` first, or fall back to the defaults below. Treat artifact-gate failures as "not found" (for example missing required files, missing hashes, or blocking `missingSources` in `constraints.json`).
+
+## Scaffolding Steps
+
+### 1. Determine rule location
+
+Rules live under the plugin source tree:
+
+```
+plugins/rules/<module-alias>/src/main/java/com/fluentcommerce/rule/
+├── common/           # Entity-agnostic rules
+├── fulfilment/       # Fulfilment-specific rules
+├── variantproduct/   # Product-specific rules
+├── order/            # Order-specific rules (create if needed)
+└── returnorder/      # Return order rules (create if needed)
+```
+
+### 2. Create the rule class
+
+Write the Java file at the appropriate package path using the template above. Replace all `<PLACEHOLDERS>`.
+
+### 3. Create the test class
+
+Write the test at the mirror path under `src/test/java/`. Test class name = `<RuleName>Test.java`.
+
+### 4. Wire into module.json
+
+Add the rule name to the `rules` array in the module's `resources/module.json`:
+
+```json
+{
+  "rules": [
+    "ExistingRule1",
+    "ExistingRule2",
+    "NewRuleName"
+  ]
+}
+```
+
+### 5. Verify compilation
+
+```bash
+cd plugins/ && mvn clean install -pl rules/<module-alias> -am
+```
+
+If Maven fails, check:
+- Node.js version (must be 18 for Apollo codegen): `nvm use 18` on Unix; on Windows with nvm-windows (nvm4w), use the full version number: `nvm use 18.x.x`
+- Import paths are correct
+- `BaseRule` and `ContextWrapper` are in the `common` package
+
+## Rules That Use Dynamic GraphQL
+
+For rules that need to query or mutate entities dynamically:
+
+```java
+import com.fluentcommerce.util.dynamic.DynamicUtils;
+
+// Query entity fields via JSON paths
+List<String> paths = Arrays.asList("ref", "status", "fulfilments.ref", "fulfilments.status");
+JsonNode result = DynamicUtils.query(context, paths, "orderQuery", null);
+
+// Mutate entity
+Map<String, Object> values = new HashMap<>();
+values.put("id", entityId);
+values.put("status", "NEW_STATUS");
+values.put("attributes", attributeList);
+DynamicUtils.mutate(context, values);
+```
+
+**Path syntax:** Omit `edges` and `node` — DynamicEntityQuery adds them automatically. Use `items.product.name` not `items.edges.node.product.name`.
+
+## Rules That Read Settings
+
+```java
+import com.fluentcommerce.util.SettingUtils;
+import com.fluentretail.rubix.foundation.graphql.type.Setting;
+
+Setting setting = SettingUtils.getSettingByRef(context, "my.setting.ref");
+JsonNode config = JsonUtils.stringToPojo(setting.getLobValue(), JsonNode.class);
+```
+
+## Post-Scaffold Validation
+
+After generating rule files, verify the output before handing off to `/fluent-build`:
+
+1. **Java syntax check** — Read the generated `.java` file and confirm it parses (no unclosed braces, missing imports, or placeholder text like `TODO` or `FIXME` in logic paths)
+2. **Test file exists** — Confirm the test class was generated alongside the rule class
+3. **module.json wired** — Read `resources/module.json` and verify the new rule name appears in the `rules` array
+4. **No duplicate registrations** — Confirm the rule name doesn't appear twice in `module.json`
+5. **Compilation check** — Run `mvn compile -pl plugins -q` (or the module's build command) to verify the generated Java compiles without errors. If Maven is unavailable, recommend `/fluent-build` immediately to catch compilation issues early
+
+If any check fails, fix before proceeding. Do not hand off a broken scaffold to `/fluent-build`.
+
+## 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 |
+|----------------|-------------|------|
+| Generated Java rule class | `/fluent-build` | `accounts/<PROFILE>/SOURCE/<repo>/plugins/rules/<alias>/src/main/java/.../<RuleName>.java` |
+| Generated test class | `/fluent-build` | `accounts/<PROFILE>/SOURCE/<repo>/plugins/rules/<alias>/src/test/java/.../<RuleName>Test.java` |
+| Updated module.json | `/fluent-module-validate` | `accounts/<PROFILE>/SOURCE/<repo>/resources/module.json` |
+
+## Error Reporting
+
+Errors from this skill follow the standard format:
+
+| Field | Description |
+|-------|-------------|
+| `phase` | Skill phase where error occurred (e.g., `pre-flight`, `scaffold`, `validation`, `wiring`) |
+| `severity` | `CRITICAL` (blocks downstream), `HIGH` (needs fix), `MEDIUM` (advisory), `LOW` (informational) |
+| `message` | Human-readable error description |
+| `resolution` | Suggested fix or downstream skill to invoke |
+
+## Post-Flight Verification
+
+After scaffolding completes, verify the generated code:
+
+1. **Compile check**: Run `mvn compile -pl plugins/<module-name>` to verify generated Java compiles without errors.
+2. **Test compile check**: Run `mvn test-compile -pl plugins/<module-name>` to verify the test class compiles.
+3. **Registration check**: Read `module.json` back and confirm the new rule appears in the `rules` array with correct `name`, `class`, and `type`.
+4. **If compilation fails**: Fix the issue (missing imports, incorrect class name, typo) before declaring the scaffold complete. Do not proceed to next steps with broken code.
+
+## Gotchas
+
+- **`@ParamString` names are CASE-SENSITIVE** — `"jsonpath"` and `"jsonPath"` are different props
+- **`context.action().mutation()` only QUEUES** — the mutation executes AFTER the rule returns
+- **`DynamicMutation.buildMutationDocument` appends `!`** — never include `!` in type names
+- **`updateFulfilmentItem` does NOT exist** — use `updateFulfilment` with nested `items` array
+- **BaseRule wraps Context** — implement `run(ContextWrapper context)`, not `run(Context context)`
+
+## Post-Execution: Feedback Capture
+
+After completing this skill (whether success or failure), write a feedback record:
+
+1. **Classify outcome:** `SUCCESS` (clean scaffold), `PARTIAL_SUCCESS` (scaffolded after fixing issues), `FAILURE` (could not complete), `BLOCKED` (no module found), `USER_CORRECTED` (user overrode approach)
+2. **Build record:** Create a `feedback-record-v1` JSON object with:
+   - `skill`: `"fluent-rule-scaffold"`
+   - `feature`: feature slug if applicable
+   - `entityType` / `entitySubtype`: from the rule's target entity
+   - `phases`: trace of each phase (pre-flight, plan, generate-class, generate-test, wire-module-json, compile-check) with PASS/FAIL/SKIP
+   - `learnings`: any gotchas discovered during execution
+   - `userCorrections`: any corrections the user provided
+3. **Redact secrets.** Keep business identifiers.
+4. **Append** one JSON line to `accounts/<PROFILE>/feedback/fluent-rule-scaffold.jsonl`
+5. **Update** `accounts/<PROFILE>/feedback/index.json` counters (create with `mkdir -p` if missing)
+
+**Skip capture if:** The execution was trivially simple (e.g., user just asked a question, no actual scaffolding happened).
+
+## Known Pitfalls
+<!-- feedback-promoted: managed section, updated by feedback loop -->
+
+_(No promoted learnings yet.)_
+
+<!-- end feedback-promoted -->