@fluentcommerce/ai-skills 0.1.0

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

@@ -0,0 +1,385 @@
+---
+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
+
+**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)`