@fluentcommerce/ai-skills 0.1.0

package/content/dev/skills/fluent-feature-plan/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: fluent-feature-plan
+description: Produce comprehensive feature implementation plans with universal NEW/EXISTING/MODIFIED/REUSED/OOTB classification across all artifacts. Covers rules, workflows, settings, webhooks, GraphQL operations, cross-entity flows, and deployment. Triggers on "plan feature", "feature plan", "plan implementation", "design feature", "plan this feature", "what do I need to build".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <feature-description> [--profile PROFILE] [--retailer RETAILER_REF]
+---
+
+# Feature Planner
+
+Produce comprehensive, self-contained implementation plans for Fluent Commerce features. A "feature" spans multiple artifacts — rules, workflow rulesets, settings, webhooks, entity types, and deployments. The plan is the contract — an implementer can write code from it without ambiguity.
+
+## Template Reference
+
+**The full plan template with worked examples and section applicability guide lives at: `PLAN_TEMPLATE.md` (in this skill directory).**
+
+Read that file before producing any plan. It defines:
+- The 18-section structure with TOC (including §6.1 Complete Workflow Inventory and §3.6 Workflow Processing Flow)
+- Universal Source classification (NEW / EXISTING / MODIFIED / REUSED / OOTB)
+- Section applicability guide (which sections are required vs optional)
+- Rules classification decision flow
+- Diagram requirements (Mermaid stateDiagram-v2, sequenceDiagram, flowchart)
+- Plan lifecycle (PENDING → APPROVED → implementation)
+
+## When to Use
+
+Use `/fluent-feature-plan` when the work involves **multiple artifacts**:
+- A new capability needing workflow changes + new rules + settings + possibly webhooks
+- A change spanning multiple entity types (ORDER → FULFILMENT → LOCATION)
+- Any implementation request where the scope isn't covered by a single skill
+
+**For single-artifact work**, the individual skill's Planning Gate is sufficient:
+- Single new rule → `/fluent-rule-scaffold` Planning Gate
+- Single workflow edit → `/fluent-workflow-builder` Planning Gate
+- Settings-only change → `/fluent-settings` Planning Gate
+- Retrospective feature documentation → `/fluent-feature-explain`
+- Scope document decomposition → `/fluent-scope-decompose`
+
+## Phase 1: Discovery
+
+Before writing a plan, gather evidence to classify every artifact.
+
+### 1.1 OOTB Rule Search
+
+```
+plugin.list name="<keyword>"     # e.g., "Fulfilment", "Pickup", "Webhook"
+plugin.list name="SendEvent"     # standard event forwarding rules
+plugin.list compact=true         # full inventory (compact payload)
+```
+
+Determine which parts of the feature can use OOTB rules vs. need custom. For every rule the feature needs, try to find an OOTB match FIRST.
+
+### 1.2 Existing Workflows
+
+```bash
+# Check what's deployed
+fluent workflow list -p <PROFILE> -r <RETAILER_REF>
+# Download if not local
+fluent workflow download -p <PROFILE> -r <RETAILER_REF> -w all -o accounts/<PROFILE>/workflows/<RETAILER_REF>/
+```
+
+Read workflow JSONs to map existing statuses, rulesets, and triggers. Identify which workflows need modification and their current versions.
+
+**For §6.1 Complete Workflow Inventory:** Parse each modified workflow's JSON to extract the complete ruleset list — entity type, subtype, trigger event, trigger status, and rule names. This feeds directly into the §6.1 table and §3.6 Workflow Processing Flow diagram. Don't rely on the implementer to manually enumerate rulesets.
+
+### 1.3 Existing Settings
+
+```bash
+# Via MCP
+graphql.query: settings(first: 100) filtered by name pattern
+# Or via CLI
+fluent setting list -p <PROFILE> -r <RETAILER_REF> -n "*keyword*"
+```
+
+Find settings that already exist vs. need creation.
+
+### 1.4 Local Source Analysis
+
+Search `accounts/<PROFILE>/SOURCE/` for:
+- `module.json` — rule registrations
+- `source-map.json` — if `/fluent-custom-code` was run
+- `behavior-map.md` — rule behavior descriptions
+- Existing Java rule classes for reusable patterns
+
+### 1.5 Module Identification
+
+Identify the target module for new custom rules:
+- Search `accounts/<PROFILE>/SOURCE/` for existing modules
+- If no module exists, flag `/fluent-module-scaffold` as a prerequisite task
+
+## Phase 2: Classification
+
+For EVERY artifact the feature touches, apply one of these labels:
+
+| Label | Meaning | Required Detail in Plan |
+|-------|---------|------------------------|
+| **NEW** | Doesn't exist yet, must be created | Full pseudo logic / value shape / trigger spec |
+| **EXISTING** | Already deployed, no modification needed | State current value, confirm no change |
+| **MODIFIED** | Already exists but needs changes | Show before → after diff |
+| **REUSED** | Pattern exists in codebase, copy the approach | Reference source file/rule |
+| **OOTB** | Platform rule, use with configuration only | State which props/values to configure |
+
+This applies universally across ALL plan sections — rules, rulesets, statuses, settings, webhooks, GraphQL operations, cross-entity impacts, files.
+
+## Phase 3: Pseudo Logic for NEW Rules
+
+For every **NEW** rule, write pseudo logic that is:
+- **Unambiguous** — a developer can implement from it without asking questions
+- **Shows data flow**: READ → VALIDATE → QUERY → BUILD → MUTATE → LOG
+- **Shows branching**: IF/ELSE with error paths and thrown exceptions
+- **References specific APIs**: `DynamicUtils.queryList()`, `SettingUtils.getSettingByRef()`, `JsonUtils.getJsonPath()`
+- **Stays at design level** — NOT Java code, but precise enough to translate directly
+
+```
+FUNCTION run(context):
+    order = context.getEntity()
+    event = context.getEvent()
+
+    // 1. Extract required fields
+    pickupLocationRef = extractFromPath(event, props.pickupLocationPath)
+    IF pickupLocationRef IS NULL:
+        THROW "Pickup location ref required but null at path: {pickupLocationPath}"
+
+    // 2. Fetch order items
+    items = DynamicUtils.queryList(context, "items", OrderItem.class, null)
+    IF items IS EMPTY:
+        THROW "Order has no items — cannot create fulfilment"
+
+    // 3. Read config from setting
+    config = SettingUtils.getSettingByRef(context, props.configSettingName)
+    maxPickupHours = config.lobValue.maxPickupHours
+
+    // 4. Validate
+    IF requestedPickupTime > order.createdOn + maxPickupHours hours:
+        THROW "Pickup window expired"
+
+    // 5. Build and mutate
+    fulfilmentRef = "CURB-{order.ref}-{pickupLocationRef}"
+    DynamicUtils.create(context, CreateFulfilmentInput { ref, type, items, attributes })
+
+    // 6. Log
+    context.addLog("Created curbside fulfilment {fulfilmentRef}")
+```
+
+**For OOTB rules**: just state the configuration props to set in the ruleset — no pseudo logic needed.
+
+**For EXISTING rules**: confirm "no code changes" or describe the modification.
+
+## Phase 4: Plan Writing
+
+**Write to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-feature-plan-<slug>.md`
+
+Follow the 18-section template from `PLAN_TEMPLATE.md` (sibling file). Validate all Mermaid diagram blocks per `/fluent-mermaid-validate` before writing the plan file. Key per-section notes:
+
+| Section | Source-Column Required | Key Content |
+|---------|----------------------|-------------|
+| §4 Workflows | Yes (NEW/EXISTING/MODIFIED) | Workflow name, current version, action |
+| §5 Statuses | Yes | Status, entity type, which ruleset adds it |
+| §6 Rulesets | Yes | Trigger event, from/to status, ordered rule list with source annotations |
+| §6.1 Complete Workflow Inventory | Yes (when modifying) | ALL rulesets in each modified workflow with NEW/EXISTING/MODIFIED annotations |
+| §3.6 Workflow Processing Flow | Yes (when modifying) | Flowchart: complete status→ruleset→status chain, NEW/MODIFIED highlighted |
+| §7 Rules Inventory | Yes | ALL rules for the feature with source + purpose |
+| §8 Detailed Design | For NEW rules only | Class, params table, pseudo logic, GraphQL ops |
+| §9 Settings | Yes | Context, contextId, value type, JSON example for NEW |
+| §10 Webhooks | Yes | Setting name, method, payload shape |
+| §11 Scheduled Events | Yes | Event name, delay, purpose |
+| §12 GraphQL Ops | Yes (NEW/REUSED) | Query/mutation, root field, selected paths |
+| §13 Cross-Entity | Yes | Source → target entity, mechanism |
+| §14 Files | Yes (NEW/MODIFIED) | All created/modified files |
+
+## Phase 5: Approval
+
+1. Set `Status: PENDING`, `Revision: 1`
+2. Present the full plan content to the user
+3. Wait for explicit approval before any implementation
+4. On approval: update `Status: APPROVED`, `Approved by: user`
+5. On rejection: increment `Revision`, revise, re-present
+6. On "just do it": write `Status: APPROVED (auto-skip)`, `Approved by: user (gate skipped)`, proceed
+
+## Phase 6: Handoff to Implementation Skills
+
+After approval, the plan becomes the source of truth. Each skill reads its relevant sections:
+
+| Artifact Type | Implementation Skill | Plan Sections |
+|--------------|---------------------|---------------|
+| New custom rules | `/fluent-rule-scaffold` | §7 Rules, §8 Detailed Design |
+| Workflow changes | `/fluent-workflow-builder` | §4 Workflows, §5 Statuses, §6 Rulesets |
+| Settings | `/fluent-settings` | §9 Settings |
+| Module validation | `/fluent-module-validate` | §17 Deployment (step 1) |
+| Module build | `/fluent-build` | §17 Deployment (step 2) |
+| Pre-deploy check | `/fluent-pre-deploy-check` | §17 Deployment (step 3) |
+| Module deploy | `/fluent-module-deploy` | §17 Deployment (step 4) |
+| Workflow deploy | `/fluent-workflow-deploy` | §17 Deployment (steps 5-6) |
+| Data module scaffold | `/fluent-data-module-scaffold` | When the feature requires data modules (no Java) |
+| E2E verification | `/fluent-e2e-test` | §16 Test Plan |
+
+The deployment sequence in §17 defines execution order. Track tasks from §17 via TodoWrite.
+
+**Module-first deployment:** When workflows are bundled inside the module (`resources/workflows/`), `fluent module install` deploys rules, workflows, and settings together. The separate `/fluent-workflow-deploy` step (steps 5-6) is only needed for standalone workflows NOT included in the module, or when workflows were excluded during module install (`--exclude workflows`).
+
+**Critical ordering constraint:** Module deploy (registers rules) MUST complete before workflow deploy (references rules). Deploying workflows that reference unregistered custom rules causes NO_MATCH events at runtime. The §17 template enforces this: workflow deploy steps depend on module deploy.
+
+**Version bump required for any content change:** Any change to Java code, workflow JSONs, settings, or resources requires bumping the module version in BOTH `resources/module.json` AND all `pom.xml` files. See `/fluent-build` for the sync procedure.
+
+**Validation chain:** `/fluent-module-validate` -> `/fluent-build` -> `/fluent-pre-deploy-check` -> `/fluent-module-deploy`. The pre-deploy check is the final gate before deployment and produces a READY/BLOCKED verdict.
+
+## Updating a Plan Mid-Implementation
+
+If discovery during implementation reveals missing artifacts:
+
+1. Edit the plan file in place — increment `Revision: N+1`
+2. Add a revision note at the bottom with what changed and why
+3. Re-present the changed sections for approval
+4. Continue from the updated plan
+
+## Cross-References
+
+| For | Use |
+|-----|-----|
+| Plan template structure & worked examples | `PLAN_TEMPLATE.md` (in this skill directory) |
+| OOTB rule search | `plugin.list` via MCP |
+| Workflow analysis | `/fluent-workflow-analyzer` |
+| Custom code analysis | `/fluent-custom-code` |
+| Connection topology | `/fluent-connection-analysis` |
+| Scope decomposition (from scope docs) | `/fluent-scope-decompose` |
+| Feature reverse-engineering (existing) | `/fluent-feature-explain` |
+| Module scaffolding (if needed) | `/fluent-module-scaffold` |

package/content/dev/skills/fluent-job-batch/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: fluent-job-batch
+description: Diagnose and monitor JOB/BATCH orchestration entity lifecycles in Fluent Commerce. Covers JOB and BATCH entity workflows, status tracking, failure investigation, and performance monitoring. Distinct from batch data ingestion API. Triggers on "job batch", "batch management", "job lifecycle", "job status", "batch monitoring", "batch operations", "job entity".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: [--job-id <id>] [--batch-id <id>] [--status ACTIVE|COMPLETED|FAILED]
+---
+
+# JOB/BATCH Orchestration Lifecycle
+
+Monitor and diagnose JOB and BATCH entity orchestration workflows in Fluent Commerce.
+
+## Ownership Boundary
+
+This skill owns JOB/BATCH entity lifecycle diagnostics and monitoring.
+
+- **Batch data ingestion API** (batch.create/send/status/results) → `/fluent-mcp-tools`
+- **Event query syntax** → `/fluent-event-api`
+- **Root cause diagnosis** → `/fluent-trace`
+- **Workflow structure** → `/fluent-workflow-analyzer`
+
+## Disambiguation: JOB/BATCH Orchestration vs Batch Ingestion API
+
+| Concept | What It Is | Skill |
+|---------|-----------|-------|
+| **JOB entity** | Root orchestratable entity with its own workflow (like ORDER or LOCATION) | This skill |
+| **BATCH entity** | Child entity of JOB, progresses through workflow states | This skill |
+| **batch.create/send/status/results** | MCP tools for uploading data records to Fluent via batch ingestion | `/fluent-mcp-tools` |
+
+The batch ingestion API *creates* JOB and BATCH entities. This skill covers what happens *after* creation — the orchestration lifecycle.
+
+## JOB Entity Lifecycle
+
+JOB is one of the 10 root entity types that can have orchestration workflows.
+
+### Status Flow
+```
+ACTIVE → COMPLETED (all batches succeeded)
+ACTIVE → FAILED (one or more batches failed)
+```
+
+### Key Behaviors
+- **Auto-close:** JOB entities automatically close at midnight UTC
+- **Workflow type:** `JOB::<subtype>` (subtype varies by implementation)
+- **Root entity:** JOB is always its own root entity in event context
+
+## BATCH Entity Lifecycle
+
+BATCH entities are children of JOB, similar to how FULFILMENT is a child of ORDER.
+
+### Status Flow
+```
+CREATE → BATCH_COMPLETE
+```
+
+### Key Behaviors
+- **Operations:** Each BATCH contains multiple GraphQL mutations and webhook calls
+- **Metrics:** Success rates, operation counts, performance tracking per batch
+
+## Diagnostic Queries
+
+### Find JOB Events
+```
+event.list({
+  "context.entityType": "JOB",
+  "eventType": "ORCHESTRATION",
+  "from": "<time_window_start>",
+  "count": 50
+})
+```
+
+### Find BATCH Events for a JOB
+```
+event.list({
+  "context.rootEntityType": "JOB",
+  "context.rootEntityId": "<JOB_ID>",
+  "context.entityType": "BATCH",
+  "count": 100
+})
+```
+
+### Find Failed Batches
+```
+event.list({
+  "context.entityType": "BATCH",
+  "eventStatus": "FAILED",
+  "from": "<time_window_start>",
+  "count": 50
+})
+```
+
+### Query JOB Entity State
+```graphql
+{
+  jobs(id: [<JOB_ID>], first: 1) {
+    edges {
+      node {
+        id
+        ref
+        status
+        type
+        createdOn
+        updatedOn
+        attributes { name type value }
+      }
+    }
+  }
+}
+```
+
+Note: The `jobs` GraphQL query root may not exist in all Fluent versions. If unavailable, use event.list to track JOB lifecycle via events.
+
+## Troubleshooting
+
+### JOB Stuck in ACTIVE
+1. Check if batches are still processing: query BATCH events for the JOB
+2. Check if auto-close time has passed (midnight UTC)
+3. Check for exceptions: `event.list({ category: "exception", "context.rootEntityType": "JOB", "context.rootEntityId": "<ID>" })`
+
+### BATCH Failed
+1. Get exception details: `event.list({ category: "exception", "context.entityType": "BATCH", "context.entityId": "<BATCH_ID>" })`
+2. Check operation details in event attributes
+3. Hand off to `/fluent-trace` for root cause analysis
+
+### Performance Issues
+1. Check batch operation timing via `startTimer`/`stopTimer` in audit events
+2. Use `metrics.topEvents` to see if JOB/BATCH events are unusually high-volume
+3. Compare batch sizes and operation counts across jobs
+
+## Integration with Other Skills
+
+| Need | Skill |
+|------|-------|
+| Batch data upload (batch.create/send) | `/fluent-mcp-tools` |
+| Event query syntax and filters | `/fluent-event-api` |
+| Root cause for failed batches | `/fluent-trace` |
+| JOB workflow structure | `/fluent-workflow-analyzer` |
+| Event volume analytics | `/fluent-system-monitoring` |

package/content/dev/skills/fluent-mermaid-validate/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: fluent-mermaid-validate
+description: Validate Mermaid diagram syntax before including in plans, docs, or workflow analysis. Catches common pitfalls in stateDiagram-v2, sequenceDiagram, flowchart, and erDiagram. Not user-invocable — called internally by skills that generate diagrams.
+user-invocable: false
+allowed-tools: Read
+---
+
+# Mermaid Syntax Validator
+
+Validate all Mermaid diagram blocks before writing them to files. This skill is a reference for common syntax pitfalls — apply these rules whenever generating Mermaid diagrams.
+
+## When to Apply
+
+Every time you generate a Mermaid code block (` ```mermaid ... ``` `), validate it against the rules below BEFORE writing to a file. This applies to all diagram types used in Fluent Commerce skills.
+
+## Common Pitfalls by Diagram Type
+
+### stateDiagram-v2
+
+| Pitfall | Bad | Good |
+|---------|-----|------|
+| Colon in note text | `note right of S : FC routing: HD / CC` | `note right of S : FC routing (HD, CC)` |
+| Special chars in transition labels | `S1 --> S2 : All shipped/collected` | `S1 --> S2 : All shipped or collected` |
+| Missing space before colon | `S1 --> S2: label` | `S1 --> S2 : label` |
+| Unicode arrows in labels | `S1 --> S2 : A → B` | `S1 --> S2 : A then B` |
+| Em dash in text | `note right of S : No changes — done` | `note right of S : No changes. Done` |
+| Unquoted state with spaces | `state "My State" as MS` | OK (quoted is correct) |
+| Duplicate state names without alias | Two states named `CREATED` for different entities | Use `state "CREATED" as FUL_CREATED` |
+
+**Key rule:** After the `:` separator in notes and transitions, the remaining text must NOT contain `:`, `→`, `—`, or `/`.
+
+### sequenceDiagram
+
+| Pitfall | Bad | Good |
+|---------|-----|------|
+| Colon in message text | `A->>B: Read curbside.pickup.config` | `A->>B: Read curbside pickup config` |
+| Colon in Note text | `Note over A,B: attrs: x, y` | `Note over A,B: attrs include x, y` |
+| Arrow (→) in message | `A->>A: CREATED → BOOKED` | `A->>A: CREATED then BOOKED` |
+| Participant name with special chars | `participant FC as FULFILMENT_CHOICE (CC)` | `participant FC as FULFILMENT_CHOICE` |
+| Missing participant declaration | Using `WH` without declaring it | `participant WH as Webhook` |
+| `<br/>` in messages | Works in some renderers | Prefer `\n` or split into separate messages |
+
+**Key rule:** Message text after the `:` must not contain another `:`. Use commas, parentheses, or rephrase.
+
+### flowchart (TD/LR)
+
+| Pitfall | Bad | Good |
+|---------|-----|------|
+| Unicode arrows in node label | `A[READY → RECEIVED → PICKPACK]` | `A["READY - RECEIVED - PICKPACK"]` |
+| Colon in node label | `A[type: CURBSIDE]` | `A["type CURBSIDE"]` or `A[type=CURBSIDE]` |
+| Unquoted label with special chars | `A[Pick & Pack]` | `A["Pick & Pack"]` |
+| Parentheses in unquoted label | `A[SendEvent(name)]` | `A["SendEvent(name)"]` |
+| Subgraph with colon | `subgraph FC: Processing` | `subgraph FC Processing` |
+| classDef with missing style | `classDef added` | `classDef added fill:#90EE90` |
+
+**Key rule:** If a node label contains ANY special characters (`:`, `→`, `&`, `(`, `)`, `/`), wrap it in double quotes.
+
+### erDiagram
+
+| Pitfall | Bad | Good |
+|---------|-----|------|
+| Colon in attribute | `string ref : "order ref"` | `string ref "order ref"` |
+| Relationship without label | `ORDER ||--o{ FULFILMENT` | `ORDER ||--o{ FULFILMENT : has` |
+
+## Universal Rules
+
+1. **No colons in free text** — After the initial `:` separator, never use another `:` in the same line
+2. **No unicode arrows** — Replace `→` with `then`, `to`, or `-`; replace `←` with `from`
+3. **No em dashes** — Replace `—` with `.` or `,` or rephrase
+4. **No forward slashes in labels** — Replace `HD/CC` with `HD, CC` or `HD or CC`
+5. **Quote complex labels** — Any flowchart node label with special characters must be in double quotes
+6. **Validate state names** — State names in `stateDiagram-v2` must be alphanumeric + underscore only
+7. **Consistent arrow style** — Use `-->` for state transitions, `->>` for sequence messages, `-->` for flowchart edges
+
+## Validation Checklist
+
+Before writing any file containing Mermaid blocks, verify each block:
+
+- [ ] No colons in free text after the separator colon
+- [ ] No unicode arrows (→, ←, ↔) anywhere in the diagram
+- [ ] No em dashes (—) in labels or notes
+- [ ] No forward slashes in labels or notes
+- [ ] Flowchart node labels with special chars are double-quoted
+- [ ] All participants declared in sequenceDiagram
+- [ ] stateDiagram-v2 state names are simple identifiers
+- [ ] classDef declarations include style properties