@fluentcommerce/ai-skills 0.13.0 → 0.15.0

package/content/dev/agents/fluent-backend-dev.md

@@ -16,7 +16,7 @@ skills:
   - fluent-data-module-scaffold
   - fluent-module-validate
   - fluent-build
-  - fluent-source-onboard
+  - fluent-module-convert
   - fluent-trace
   - fluent-entity-flow-diagnose
   - fluent-event-api
@@ -202,7 +202,7 @@ Execute the approved plan:
 | Scaffold data modules | `/fluent-data-module-scaffold` | Data-only modules |
 | Validate modules | `/fluent-module-validate` | Module structure checks |
 | Build modules | `/fluent-build` | Maven compile + package |
-| Onboard source | `/fluent-source-onboard` | Import non-standard code |
+| Convert to module | `/fluent-module-convert` | Convert plugins/source to module format |
 | Manage settings | `/fluent-settings` | Settings lifecycle |
 | Configure retailer | `/fluent-retailer-config` | Environment bootstrap |
 | Trace events | `/fluent-trace` | Event forensics |

package/content/dev/agents/fluent-dev.md

@@ -26,7 +26,7 @@ skills:
   - fluent-data-module-scaffold
   - fluent-module-validate
   - fluent-build
-  - fluent-source-onboard
+  - fluent-module-convert
   - fluent-trace
   - fluent-entity-flow-diagnose
   - fluent-event-api

package/content/dev/agents/fluent-frontend-dev.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-frontend-dev
-description: Fluent Commerce frontend development agent for Mystique UI framework. Builds, validates, scaffolds, and analyzes Mystique manifests and SDK component projects. Triggers on "build manifest", "create page", "validate UI", "scaffold component", "analyze manifest", "mystique", "frontend", "ui component".
+description: Fluent Commerce frontend development agent for Mystique UI framework. Builds, validates, scaffolds, and analyzes Mystique manifests and SDK component projects. Triggers on "build manifest", "create page", "validate UI", "scaffold component", "analyze manifest", "mystique", "frontend", "ui component", "new app", "build app", "create app".
 tools: Bash, Read, Write, Edit, Glob, Grep
 model: inherit
 skills:

package/content/dev/skills/fluent-account-snapshot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-account-snapshot
-description: Lightweight account state snapshot — retailers, workflows, modules, catalogues, settings, UI customizations. MCP-first data collection with LLM summary. Triggers on "account snapshot", "account state", "account inventory", "what's in this account", "environment summary".
+description: Lightweight account state snapshot covering retailers, workflows, modules, catalogues, settings, and UI customizations with MCP-first data collection. Use for account inventory or environment summary.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--profile <name>] [--retailer <ref>] [--include <sections>] [--json] [--refresh]

package/content/dev/skills/fluent-archive/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-archive
-description: Archive completed or abandoned features by transitioning status.json to ARCHIVED state, generating a closeout archive summary, and optionally cleaning up ephemeral reports. This is a lifecycle state-machine transition, not a session audit or change log, and it should win whenever the user wants a feature formally closed out. Triggers on "archive feature", "mark as archived", "close feature". ROUTING PRIORITY — if the prompt says "archive", "ARCHIVED", "closeout summary", "close feature", "mark as archived", or "feature done", route HERE — do NOT route to fluent-session. This skill transitions status.json and generates closeout summaries. fluent-session tracks file changes, which is completely different. Triggers also on "archive this feature", "generate closeout", "formally close". It does NOT handle session summaries (use fluent-session), feature status tables (use fluent-feature-status), or change audits.
+description: Archive completed or abandoned features by transitioning status.json to ARCHIVED state and generating a closeout summary. Use when formally closing out a feature or marking it as archived.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <feature-slug> [--profile PROFILE] [--reason completed|abandoned|superseded] [--cleanup] [--force]
 cursor-tier: auto
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "archive", "ARCHIVED", "closeout summary", "close feature", "mark as archived", or "feature done", route HERE — do NOT route to fluent-session. This skill transitions status.json and generates closeout summaries. fluent-session tracks file changes, which is completely different. Does NOT handle session summaries (use fluent-session), feature status tables (use fluent-feature-status), or change audits. -->
 
 # Feature Archival
 

package/content/dev/skills/fluent-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-build
-description: Build, version, and package Fluent Commerce extension modules. Handles Maven compilation, version bumping, version sync, CHANGELOG updates, git tagging, and module packaging. Use this when the user wants to compile, package, prepare, or release an artifact; do not use it for read-only deploy-readiness checks, which belong to fluent-pre-deploy-check. Triggers on "build module", "bump version", "package module", "maven build", "version status", "tag release", "version sync", "what version", "prepare release".
+description: Build, version, and package Fluent Commerce extension modules with Maven compilation, version bumping, CHANGELOG updates, and git tagging. Use when compiling, packaging, or preparing a module release.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [build|version|package|deploy|full|status|bump|sync|tag] [--skip-tests] [--level patch|minor|major] [--dry-run]
@@ -78,7 +78,7 @@ This skill does **not** own deployment runbooks. For deployment:
 
 | Signal | Condition | Example |
 |--------|-----------|---------|
-| `-> READY: <path>` | Build successful, artifact produced | `-> READY: accounts/MY_PROFILE/SOURCE/backend/fc-module-my-extensions/dist/module-0.0.30.jar` |
+| `-> READY: <path>` | Build successful, artifact produced | `-> READY: accounts/MY_PROFILE/SOURCE/backend/fc-module-my-extensions/dist/fluent-commerce-my-extensions-0.0.30.zip` |
 | `-> NEXT: /fluent-<skill>` | Ready for pre-deploy check | `-> NEXT: /fluent-pre-deploy-check` |
 | `-> BLOCKED: <reason>` | Build failed | `-> BLOCKED: VALIDATION_FAILED — Compilation error in CancelOrderRule.java:45` |
 

package/content/dev/skills/fluent-connection-analysis/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-connection-analysis
-description: Analyze workflow connection topology across multiple rulesets and workflows. Produces internal/cross-entity/cross-workflow edge maps, static-vs-dynamic runtime diffs, orphaned ruleset detection across workflow boundaries, and webhook/setting conformance inventories with Mermaid output. Use this when the question involves connection topology, cross-entity hops, cross-workflow dependencies, orphaned rulesets, runtime-vs-static drift, or mapping how work flows between rulesets/workflows. NOT for single-workflow internal structure — that stays on fluent-workflow-analyzer. ROUTING PRIORITY — if the prompt says "connection analysis", "cross-entity hops", "orphaned rulesets across workflows", "internal edges", "cross-workflow dependencies", "runtime-vs-static topology", or "connection topology", route HERE — do NOT route to fluent-workflow-analyzer. fluent-workflow-analyzer handles a SINGLE workflow's internal graph; this skill maps topology ACROSS multiple workflows and entities. Triggers on "connection analysis", "workflow connections", "map connections", "cross workflow dependencies", "cross-entity hops", "orphaned rulesets", "process flow classification", "webhook dependency map", "expected vs observed rulesets", "runtime workflow diff", "internal edges", "connection topology".
+description: Analyze workflow connection topology across multiple rulesets and workflows with edge maps, runtime diffs, and orphan detection. Use for cross-entity hops, cross-workflow dependencies, or connection topology analysis.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <workflow-file-or-name> [--deep] [--mermaid] [--output <path>] [--validate <entity-ref> --entity-type ORDER|FULFILMENT] [--from <iso> --to <iso>]
 cursor-tier: auto
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "connection analysis", "cross-entity hops", "orphaned rulesets across workflows", "internal edges", "cross-workflow dependencies", "runtime-vs-static topology", or "connection topology", route HERE — do NOT route to fluent-workflow-analyzer. fluent-workflow-analyzer handles a SINGLE workflow's internal graph; this skill maps topology ACROSS multiple workflows and entities. -->
 
 # Fluent Connection Analysis
 

package/content/dev/skills/fluent-custom-code/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: fluent-custom-code
-description: Analyze custom Fluent implementation source code under accounts/<PROFILE>/SOURCE/backend, explain behavior, and prepare safe extension plans even when repo/module layout is non-standard. ROUTING PRIORITY — source-level backend questions like "which class handles X", "which rule implements Y", "explain this custom Java plugin", or "understand this backend code before we change it" belong here, not in fluent-implementation-map or fluent-feature-explain. Workflow-name or feature-name prompts like "explain ORDER::HD end-to-end" stay on fluent-feature-explain unless the user explicitly asks about a class, plugin, module, or source file. Triggers on "analyze custom code", "explain this plugin", "extend rule logic", "understand source", "custom backend code", "which class handles", "non-standard module structure".
+description: Analyze custom Fluent implementation source code under accounts/PROFILE/SOURCE/backend, explain behavior, and prepare safe extension plans. Use for source-level backend questions about custom Java plugins, classes, or rule implementations.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <PROFILE> [--retailer <RETAILER_REF>] [--objective "<what to change>"]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — source-level backend questions like "which class handles X", "which rule implements Y", "explain this custom Java plugin" belong here, not in fluent-implementation-map or fluent-feature-explain. Workflow-name or feature-name prompts like "explain ORDER::HD end-to-end" stay on fluent-feature-explain unless the user explicitly asks about a class, plugin, module, or source file. -->
 
 # Custom Code Intelligence
 
@@ -27,7 +28,7 @@ This skill owns source discovery, code mapping, behavior explanation, and extens
 
 **Routing guardrail:** If the user is asking about source-level backend implementation inside a plugin, class, module, or repo, stay on this skill. Do NOT reroute to `/fluent-implementation-map` or `/fluent-feature-explain` unless the request is clearly about a broader feature/account architecture rather than the code itself.
 
-**HARD NEGATIVE — NOT rule-scaffold or source-onboard:** If the prompt says "analyze", "explain", "understand", or "what does this code do" about existing custom code, this is fluent-custom-code, NOT fluent-rule-scaffold (which creates NEW rules) and NOT fluent-source-onboard (which restructures code INTO module format).
+**HARD NEGATIVE — NOT rule-scaffold or module-convert:** If the prompt says "analyze", "explain", "understand", or "what does this code do" about existing custom code, this is fluent-custom-code, NOT fluent-rule-scaffold (which creates NEW rules) and NOT fluent-module-convert (which converts/restructures code INTO module format).
 
 - Workflow structure analysis is owned by `/fluent-workflow-analyzer`.
 - Runtime failure tracing is owned by `/fluent-trace`.

package/content/dev/skills/fluent-data-module-scaffold/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-data-module-scaffold
-description: Scaffold a new Fluent Commerce data module (no Java plugins). Generates module structure with assets directories, module.json, config template, and build script. ROUTING PRIORITY over fluent-module-scaffold when the user says "no Java", "no code", "workflow-only module", "JSON-only module", "data-only module", or "no compiled plugins". Any constraint that eliminates Java compilation means data module, not extension module. ROUTING PRIORITY for data-only modules — route here instead of fluent-module-scaffold when the module has no Java plugins, only workflows/settings/resources. Triggers on "create data module", "scaffold data module", "new data module", "data module", "no Java module", "workflow only module", "module without Java", "module that only has workflow JSON".
+description: Scaffold a new Fluent Commerce data module (no Java plugins) with assets directories, module.json, config template, and build script. Use for workflow-only, settings-only, or data-only modules without compiled code.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <module-name> [--profile <profile>]
 cursor-tier: auto
 planning-gate: mandatory
 ---
+<!-- routing-notes: ROUTING PRIORITY over fluent-module-scaffold when the user says "no Java", "no code", "workflow-only module", "JSON-only module", "data-only module", or "no compiled plugins". Any constraint that eliminates Java compilation means data module, not extension module. -->
 
 # Data Module Scaffolder
 
@@ -114,9 +115,9 @@ Write the plan file, present it to the user, and wait for explicit approval ("ye
 
 | Parameter | Required | Default | Description |
 |-----------|----------|---------|-------------|
-| `module-name` | Yes | -- | Module identifier (e.g., `hm-infra-data`). Lowercase alphanumeric with hyphens only. Used for directory name and `module.json` name field. |
+| `module-name` | Yes | -- | Module identifier (e.g., `acme-infra-data`). Lowercase alphanumeric with hyphens only. Used for directory name and `module.json` name field. |
 | `--description` | No | Auto-generated | Module description for `module.json` |
-| `--account-prefix` | No | Auto-detect from profile | Account/company prefix for the module name in `module.json` (e.g., `hm`, `acme`) |
+| `--account-prefix` | No | Auto-detect from profile | Account/company prefix for the module name in `module.json` (e.g., `acme`, `globex`) |
 | `--profile` | No | Active profile | Fluent CLI profile for path resolution and prefix detection |
 | `--initial-version` | No | `1.0.0` | Initial version in `module.json` |
 
@@ -150,7 +151,7 @@ The account prefix appears in the `module.json` `name` field as `<prefix>/<modul
 
 2. Else check existing modules under accounts/<PROFILE>/SOURCE/backend/
    Read any module.json and extract the prefix from the "name" field
-   e.g., "name": "hm/infra-data" --> prefix is "hm"
+   e.g., "name": "acme/infra-data" --> prefix is "acme"
 
 3. Else derive from PROFILE name (lowercase)
    MY_PROFILE --> myprofile
@@ -708,9 +709,9 @@ Follow these steps in order when scaffolding a new data module:
 
 4. COMPUTE derived values
    a. MODULE_TITLE = title-case of module-name with hyphens as spaces
-      (e.g., "hm-infra-data" --> "Hm Infra Data")
+      (e.g., "acme-infra-data" --> "Acme Infra Data")
    b. MODULE_DESCRIPTION = description from --description or auto-generated
-      (e.g., "Data module for Hm Infra Data")
+      (e.g., "Data module for Acme Infra Data")
 
 5. CREATE directory structure
    a. Create the root: accounts/<PROFILE>/SOURCE/backend/<module-name>/

package/content/dev/skills/fluent-e2e-test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-e2e-test
-description: Run end-to-end test sequences for Fluent Commerce workflows. Discover environment, create entities dynamically, fire events, poll statuses, assert state transitions, and report results. Use this when the user explicitly wants a test scenario or verification run, not when they want an autonomous orchestrator to keep pursuing a broad goal across multiple skills. Triggers on "run e2e test", "test order flow", "test workflow", "e2e test", "integration test".
+description: Run end-to-end test sequences for Fluent Commerce workflows by creating entities, firing events, polling statuses, and asserting state transitions. Use for explicit test scenarios or workflow verification runs.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [scenario-name] [--order-ref <ref>] [--entity-type ORDER|FULFILMENT]

package/content/dev/skills/fluent-entity-flow-diagnose/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-entity-flow-diagnose
-description: "HARD NEGATIVE FIRST — Do NOT route here for JOB/BATCH entities: \"JOB entity stuck\", \"BATCH stuck\", \"job lifecycle\", \"batch monitoring\", \"JOB/BATCH orchestration\", \"job not progressing\", \"batch not progressing\" → ALL go to fluent-job-batch, NOT here. JOB/BATCH are specialized orchestration entities this skill does not understand. Reconstruct the full lifecycle of a real Fluent Commerce entity (ORDER, FULFILMENT, ARTICLE, etc. — NOT JOB/BATCH) from its ref or id — rebuild the complete dynamic event sequence, resolve root and child workflows, and compare observed runtime behavior against the static workflow definition to produce an expected-vs-observed diff. ROUTING PRIORITY over fluent-trace when the prompt asks to \"compare runtime vs expected workflow path\", \"expected vs observed\", \"what should have happened\", or \"diagnose and compare runtime vs workflow\". Use ONLY when the user explicitly asks to reconstruct the complete lifecycle, compare runtime vs workflow definition, or perform expected-vs-observed analysis across root and sub-entities. HARD NEGATIVE for fluent-trace confusion — Do NOT route here when the prompt says \"trace why\", \"stuck\", \"root cause\", \"not progressing\", \"correlate events with rules\", \"identify root cause\", \"show live state\", or \"debug\" WITHOUT ALSO saying \"compare runtime\", \"expected vs observed\", or \"what should have happened\". Pure first-responder debugging ALWAYS goes to fluent-trace first. Triggers on \"reconstruct lifecycle\", \"compare runtime vs workflow\", \"compare runtime vs expected\", \"full entity history\", \"expected vs observed\", \"what should have happened\", \"lifecycle reconstruction\", \"diagnose and compare\"."
+description: Reconstruct the full lifecycle of a Fluent Commerce entity and compare observed runtime behavior against the static workflow definition. Use when comparing expected vs observed entity flow or reconstructing complete lifecycle history.
 user-invocable: true
 read-only: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <entity-ref-or-id> [--entity-type <TYPE>] [--identifier-kind ref|id|auto] [--from <iso> --to <iso>] [--output <path>] [--deep]
 cursor-tier: auto
 ---
+<!-- routing-notes: HARD NEGATIVE — Do NOT route here for JOB/BATCH entities (→ fluent-job-batch). ROUTING PRIORITY over fluent-trace when the prompt asks to "compare runtime vs expected", "expected vs observed", or "what should have happened". HARD NEGATIVE for fluent-trace confusion — Do NOT route here when the prompt says "trace why", "stuck", "root cause", "not progressing", "debug" WITHOUT comparison language. Pure first-responder debugging goes to fluent-trace. -->
 
 # Entity Flow Diagnose
 

package/content/dev/skills/fluent-event-api/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-event-api
-description: "EVENT API knowledge and conceptual reference — the canonical skill for understanding the Fluent Commerce event data model, the Fluent event model, event types, event categories, event statuses, orchestration routing, how events are routed to rulesets, run-once execution model, log actions vs audit actions, and event context model. This IS a valid, actionable platform skill that reads real knowledge documents and produces structured output — NEVER classify as 'none', 'direct knowledge', or 'direct knowledge lookup'. Even if the question sounds conceptual, this skill loads knowledge/platform docs and synthesizes a referenced answer. ROUTING PRIORITY — if the prompt asks about 'event model', 'the Fluent event model', 'event types', 'event categories', 'event statuses', 'how events are routed to rulesets', 'event execution model', 'log action vs audit action', 'log actions and audit actions', 'run-once', 'sourceEvents semantics', or 'deep-dive on Event API', route HERE — do NOT route to fluent-feature-explain, fluent-workflow-analyzer, or fluent-mcp-tools. Even if the prompt mentions workflows, rulesets, `event_list`, or `sourceEvents`, semantic questions about event statuses, categories, routing, audit-vs-log actions, or execution belong HERE. fluent-feature-explain is for explaining business features; fluent-workflow-analyzer is for analyzing one workflow definition; fluent-mcp-tools is for sending events and running MCP operations; this skill owns the Event API data model itself. Triggers on 'event api', 'event types', 'event categories', 'query events', 'event model', 'the fluent event model', 'event status', 'event history', 'run once', 'log action', 'audit action', 'event execution model', 'how events are routed to rulesets', 'orchestration engine routes events', 'sourceEvents'."
+description: Event API knowledge and conceptual reference covering the Fluent Commerce event data model, event types, categories, statuses, orchestration routing, run-once execution, and log vs audit actions. Use for event model questions or API semantics.
 user-invocable: true
 read-only: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--entity-ref <ref>] [--entity-type ORDER|FULFILMENT] [--status FAILED|SUCCESS|SCHEDULED] [--type ORCHESTRATION|ORCHESTRATION_AUDIT]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt asks about "event model", "event types", "event categories", "event statuses", "how events are routed to rulesets", "run-once", "sourceEvents semantics", or "log action vs audit action", route HERE — do NOT route to fluent-feature-explain, fluent-workflow-analyzer, or fluent-mcp-tools. Even if the prompt mentions workflows, rulesets, event_list, or sourceEvents, semantic questions about the event data model belong HERE. fluent-mcp-tools is for sending events; this skill owns the Event API data model itself. -->
 
 # Fluent Commerce Event API
 
@@ -854,7 +855,7 @@ Fulfilment updates from Warehouse Management System:
   "rootEntityId": "12345",
   "entityType": "CONSIGNMENT",
   "entityId": "11111",
-  "attributes": { "trackingNumber": "1Z999AA1234567890", "status": "IN_TRANSIT", "carrierRef": "UPS" }
+  "attributes": { "trackingNumber": "TRACK-001-XYZ", "status": "IN_TRANSIT", "carrierRef": "CARRIER_STD" }
 }
 ```
 

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

@@ -1,11 +1,12 @@
 ---
 name: fluent-feature-explain
-description: Reverse-engineer and explain an existing Fluent Commerce feature. Synthesizes workflow analysis, custom code logic, connection topology, and live runtime evidence into a comprehensive, visually rich Feature Architecture Document saved to accounts/<PROFILE>/features/<slug>/architecture.md. ROUTING PRIORITY — if the prompt names a specific existing workflow or feature such as "ORDER::HD", "FULFILMENT::CC", "Home Delivery", or asks "how does this work", "reverse-engineer this feature", or "document this flow", route HERE rather than fluent-implementation-map or fluent-feature-plan. Use this for feature/flow architecture such as "how does Home Delivery work", "explain ORDER::HD end-to-end", or "document this fulfilment flow", not for source-level plugin/class questions inside custom backend code; those belong to /fluent-custom-code. Key knowledge — domain-model.md (entity relationships), workflow-json-structure.md (status machines), sync-vs-async-patterns.md (event flows). HARD NEGATIVE — Do NOT route here for: 'event lifecycle' / 'event API' / 'event flow' / 'event payload' / 'send event' / 'event attributes' (→ fluent-event-api for event-centric questions), broad account-wide inventory or "what's been built" requests (→ fluent-implementation-map), or future-change planning requests like "can we add" / "plan this change" (→ fluent-feature-plan). Triggers on "explain feature", "how does this work", "reverse engineer", "feature architecture", "document this flow", "what does this workflow do", "ORDER::HD", "FULFILMENT::CC".
+description: Reverse-engineer and explain an existing Fluent Commerce feature by synthesizing workflow analysis, custom code, connection topology, and runtime evidence into an architecture document. Use when explaining how a specific feature or workflow works.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <feature-name-or-workflow> [--depth shallow|full] [--include-runtime] [--output <path>]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt names a specific existing workflow or feature such as "ORDER::HD", "FULFILMENT::CC", or asks "how does this work" or "reverse-engineer this feature", route HERE rather than fluent-implementation-map or fluent-feature-plan. HARD NEGATIVE — Do NOT route here for event-centric questions (→ fluent-event-api), broad account-wide inventory (→ fluent-implementation-map), future-change planning (→ fluent-feature-plan), or source-level plugin/class questions (→ fluent-custom-code). -->
 
 # Feature Explainer
 

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

@@ -1,6 +1,6 @@
 ---
 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".
+description: Produce comprehensive feature implementation plans with NEW/EXISTING/MODIFIED/REUSED/OOTB classification across all artifacts including rules, workflows, and settings. Use for planning a feature implementation.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <feature-description> [--profile PROFILE] [--retailer RETAILER_REF]
@@ -96,6 +96,7 @@ Check for project-specific knowledge that should inform feature planning:
    - `knowledge/platform/reference-modules.md` — use for OOTB capabilities before planning new custom assets
    - `knowledge/platform/reusability-patterns.md` — use for deciding when to reuse patterns, extend them, or introduce new artifacts
    - `knowledge/platform/sync-vs-async-patterns.md` — use for event choreography, sequencing, and long-running orchestration choices
+   - `knowledge/platform/interaction-design-patterns.md` — use for user action patterns, module visibility, and strict action contracts (eventName, context[], modules[], attributes[])
    - `knowledge/platform/rule-development-contract.md` — **MANDATORY**: annotation contract (`@ParamString` vs `@EventAttribute`), reading patterns, enhancement protocol for Rules Inventory section
    - `knowledge/platform/create-order-reference.md` — createOrder/createReturnOrder/createFulfilment input schemas, fulfilmentChoice wiring, ORDER::MULTI patterns. Use when planning features that create or modify orders.
 4. If `accounts/<PROFILE>/memory/index.md` exists, read the top account-specific gotchas and apply them silently while planning.

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

@@ -1,6 +1,6 @@
 ---
 name: fluent-feature-status
-description: Dashboard view of all features and their lifecycle status. Scans accounts/<PROFILE>/features/*/status.json and presents a consolidated table with filtering, sorting, and workspace tree view. Triggers on "feature status", "show features", "what features", "feature dashboard", "where am I", "what's in progress".
+description: Dashboard view of all features and their lifecycle status by scanning status.json files and presenting a consolidated table with filtering and sorting. Use for feature status overview or progress tracking.
 user-invocable: true
 allowed-tools: Bash, Read, Glob, Grep
 argument-hint: [--profile PROFILE] [--filter STATUS] [--format table|json] [--tree]

package/content/dev/skills/fluent-frontend-build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-frontend-build
-description: Build, test, and validate a Mystique SDK component project. Local dev mode starts a hot-reload server on localhost:3001, wires it into the Fluent manifest, and supports live iteration. Production mode runs 7 quality gates (TypeScript, lint, tests, webpack, bundle, externals, GraphQL schema validation). Frontend equivalent of /fluent-build. Triggers on "build frontend", "build component", "yarn build", "frontend build", "sdk build", "build bundle", "test locally", "local dev", "start dev server", "run locally".
+description: Build, test, and validate a Mystique SDK component project with local dev server and 7 production quality gates. Use for frontend builds, local dev mode, or SDK bundle validation.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [project-path] [full|build|test|lint|check]

package/content/dev/skills/fluent-frontend-readme/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-frontend-readme
-description: "README.md GENERATOR for SDK projects — reads actual TypeScript/React source code and writes a README.md file with component registrations, build instructions, settings dependencies, and deployment guide. This skill writes documentation files, NOT manifest analysis. Does NOT audit code quality (→ fluent-frontend-review), does NOT analyze manifest JSON health (→ fluent-mystique-assess). ROUTING — This generates README.md documentation for SDK component projects. It does NOT analyze manifest complexity (use fluent-mystique-assess). Triggers on 'generate readme', 'document components', 'SDK readme', 'component documentation'. ROUTING PRIORITY — if the prompt says \"generate README\", \"write readme\", \"document component registrations\", \"SDK readme\", \"README for SDK project\", \"create documentation\", \"build instructions\", \"settings dependencies\", or \"document registrations\", route HERE — do NOT route to fluent-mystique-assess. fluent-mystique-assess reads manifest JSON for complexity scoring; this skill reads .ts/.tsx source files and writes a README.md. Triggers on \"generate readme\", \"document component\", \"frontend readme\", \"sdk readme\", \"component docs\", \"write readme\", \"create documentation\", \"README for SDK project\", \"document registrations\", \"README.md\", \"build instructions\", \"settings dependencies\", \"generate README.md for SDK project\". ROUTING PRIORITY for frontend documentation — route here instead of fluent-mystique-assess when prompt asks about generating README, docs, or documentation for a Mystique/frontend project."
+description: README.md generator for SDK projects that reads TypeScript/React source code and writes documentation with component registrations, build instructions, and deployment guide. Use for generating frontend project README or SDK documentation.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [project-path]
 cursor-tier: auto
 planning-gate: none
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "generate README", "write readme", "SDK readme", or "README for SDK project", route HERE — do NOT route to fluent-mystique-assess. fluent-mystique-assess reads manifest JSON for complexity scoring; this skill reads .ts/.tsx source files and writes a README.md. Does NOT audit code quality (→ fluent-frontend-review), does NOT analyze manifest JSON health (→ fluent-mystique-assess). -->
 
 # Frontend README Generator
 

package/content/dev/skills/fluent-frontend-review/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-frontend-review
-description: "SDK SOURCE CODE quality audit — reviews TypeScript/React .ts/.tsx files for strictness, React anti-patterns, SDK compliance, GraphQL schemas, test quality, and bundle size. Frontend equivalent of /fluent-custom-code. Audits SDK project source files (.ts, .tsx, package.json, webpack config) — does NOT analyze manifest JSON health (→ fluent-mystique-assess) and does NOT validate manifest schema (→ fluent-mystique-assess). ROUTING — This runs code quality review: TypeScript quality, React patterns, SDK compliance, test coverage audit. It does NOT validate manifest JSON schema (use fluent-mystique-assess). Triggers on 'code review', 'quality audit', 'review SDK code', 'frontend code patterns'. ROUTING PRIORITY — if the prompt says \"review frontend\", \"code quality audit\", \"frontend review\", \"TypeScript strictness\", \"React anti-patterns\", \"React patterns\", \"SDK compliance\", \"review source code\", \"audit SDK project\", or \"bundle size\", route HERE — do NOT route to fluent-mystique-assess. fluent-mystique-assess checks manifest JSON schema; this skill audits .ts/.tsx source files for code quality. Triggers on \"review frontend\", \"code quality\", \"frontend review\", \"review component\", \"audit sdk\", \"check quality\", \"TypeScript strictness\", \"React anti-patterns\", \"React patterns\", \"SDK compliance\", \"review source code\", \"bundle size\", \"code review\", \"quality audit\", \"review SDK code\", \"frontend code patterns\". ROUTING PRIORITY for source code quality — route here instead of fluent-mystique-assess when prompt asks about TypeScript/React code quality, code review, or source file auditing."
+description: SDK source code quality audit for TypeScript/React files covering strictness, React anti-patterns, SDK compliance, GraphQL schemas, test quality, and bundle size. Use for frontend code review or SDK project audits.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [project-path]
 cursor-tier: manual
 planning-gate: none
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "review frontend", "code quality audit", "frontend review", "TypeScript strictness", "React anti-patterns", "SDK compliance", "review source code", or "bundle size", route HERE — do NOT route to fluent-mystique-assess. fluent-mystique-assess checks manifest JSON schema; this skill audits .ts/.tsx source files for code quality. Does NOT analyze manifest JSON health (→ fluent-mystique-assess). -->
 
 # Frontend Code Review
 

package/content/dev/skills/fluent-goal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-goal
-description: "Goal-directed autonomous orchestrator. Takes any Fluent Commerce goal, decomposes into verifiable sub-goals, delegates to existing skills, verifies outcomes via MCP, self-critiques, adjusts approach, and persists until the goal is met or genuinely blocked. Triggers on 'make it work', 'keep going until', 'get this working', 'resolve end to end', 'fix until done', 'goal:', 'achieve', 'pursue goal'."
+description: Goal-directed autonomous orchestrator that decomposes any Fluent Commerce goal into verifiable sub-goals, delegates to skills, and verifies outcomes via MCP. Use when pursuing an end-to-end goal autonomously.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: "<goal in plain English>" [--autonomy guided|gated|autonomous] [--max-attempts 3] [--entity-ref <ref>]

package/content/dev/skills/fluent-implementation-map/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-implementation-map
-description: Reverse-engineer an entire Fluent Commerce implementation into a feature inventory with end-to-end flow diagrams, cross-feature dependency maps, customisation scoring, and gap analysis. Triggers on "implementation map", "what's been built", "analyze implementation", "reverse engineer account", "feature inventory", "end to end flows", "map this account", "what exists", "onboard to account".
+description: Reverse-engineer an entire Fluent Commerce implementation into a feature inventory with flow diagrams, dependency maps, and gap analysis. Use for understanding what has been built across an account.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: --profile PROFILE --retailer RETAILER [--depth summary|detailed] [--focus ENTITY_TYPE] [--include-ootb] [--create-stubs] [--include-runtime]

package/content/dev/skills/fluent-inventory-catalog/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-inventory-catalog
-description: "Manage Fluent Commerce virtual inventory: catalogues, VirtualPositions, VirtualSegments, inventory feeds, and control groups. Schema-gated — only runs when VirtualSegment type exists. Triggers on \"inventory catalog\", \"virtual position\", \"virtual segment\", \"inventory feed\", \"control group\", \"catalogue structure\", \"virtual inventory\". ROUTING — This handles virtual inventory structure queries and management. It does NOT handle account-wide snapshots (use fluent-account-snapshot) or sourcing configuration (use fluent-sourcing)."
+description: Manage Fluent Commerce virtual inventory including catalogues, VirtualPositions, VirtualSegments, inventory feeds, and control groups. Schema-gated and only runs when VirtualSegment type exists.
 user-invocable: true
 trigger-patterns:
   - "inventory catalog"
@@ -38,7 +38,7 @@ graphql_introspect({ type: "VirtualSegment" })
 - **If `VirtualSegment` type exists:** proceed.
 - **If NOT found:** STOP immediately with this message:
 
-> Virtual Segments not available on this account's schema version. This feature requires platform version with segment support (expected April 2026+). Run `graphql_introspect` with `type: 'VirtualSegment'` to check availability.
+> Virtual Segments not available on this account's schema version. Run `graphql_introspect` with `type: 'VirtualSegment'` to check if your platform version supports segments.
 
 Do NOT fall back to non-segment inventory operations. The entire skill is gated on segment support.
 

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

@@ -1,12 +1,13 @@
 ---
 name: fluent-job-batch
-description: Diagnose and monitor JOB and BATCH orchestration entities in Fluent Commerce. The dedicated skill for JOB/BATCH workflow status tracking, stuck-job investigation, batch failure triage, and job performance monitoring. Any prompt mentioning JOB or BATCH entity types routes here — not to fluent-entity-flow-diagnose or fluent-trace. Distinct from batch data ingestion API (which is fluent-mcp-tools). ROUTING PRIORITY — Any prompt mentioning "JOB" or "BATCH" entity types MUST route here, even if the prompt also says "stuck" or "diagnose". JOB/BATCH are specialized orchestration entities with unique lifecycle patterns — fluent-entity-flow-diagnose and fluent-trace do NOT understand JOB/BATCH semantics. Triggers on "job batch", "job stuck", "batch stuck", "job lifecycle", "job status", "batch monitoring", "batch operations", "job entity", "JOB/BATCH", "why is the job stuck", "batch failure", "JOB entity is stuck", "job not progressing", "batch not progressing", "job orchestration".
+description: Diagnose and monitor JOB and BATCH orchestration entities in Fluent Commerce including lifecycle tracking, stuck-job investigation, and batch failure triage. Use for any JOB or BATCH entity questions or debugging.
 user-invocable: true
 read-only: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [--job-id <id>] [--batch-id <id>] [--status ACTIVE|COMPLETED|FAILED]
 cursor-tier: auto
 ---
+<!-- routing-notes: ROUTING PRIORITY — Any prompt mentioning "JOB" or "BATCH" entity types MUST route here, even if the prompt also says "stuck" or "diagnose". JOB/BATCH are specialized orchestration entities — fluent-entity-flow-diagnose and fluent-trace do NOT understand JOB/BATCH semantics. Distinct from batch data ingestion API (→ fluent-mcp-tools). -->
 
 # JOB/BATCH Orchestration Lifecycle
 
@@ -37,7 +38,9 @@ The batch ingestion API *creates* JOB and BATCH entities. This skill covers what
 
 ## JOB Entity Lifecycle
 
-JOB is one of the 10 root entity types that can have orchestration workflows.
+> **Note:** JOB and BATCH lifecycle details below are inferred from runtime API evidence and implementation observation. They are not yet documented in the core platform knowledge base (`domain-model.md`). Validate against your environment's actual workflow definitions.
+
+JOB is a root entity type that can have orchestration workflows.
 
 ### Status Flow
 ```
@@ -46,7 +49,7 @@ ACTIVE → FAILED (one or more batches failed)
 ```
 
 ### Key Behaviors
-- **Auto-close:** JOB entities automatically close at midnight UTC
+- **Auto-close:** JOB entities automatically close at midnight UTC (observed behavior — verify via workflow definition in your environment)
 - **Workflow type:** `JOB::<subtype>` (subtype varies by implementation)
 - **Root entity:** JOB is always its own root entity in event context
 

package/content/dev/skills/fluent-knowledge-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-knowledge-init
-description: "Interactive wizard to set up project knowledge. Asks plain-English questions, ingests existing docs, or captures progressive learnings — then writes structured knowledge files. Triggers on \"knowledge init\", \"set up knowledge\", \"project knowledge\", \"teach me about your project\", \"knowledge setup\", \"onboard knowledge\"."
+description: Interactive wizard to set up project knowledge by asking questions, ingesting existing docs, or capturing progressive learnings into structured knowledge files. Use for knowledge initialization or onboarding.
 user-invocable: true
 read-only: false
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep