@fluentcommerce/ai-skills 0.13.0 → 0.15.0

package/content/dev/skills/{fluent-source-onboard → fluent-module-convert}/SKILL.md

@@ -1,22 +1,22 @@
 ---
-name: fluent-source-onboard
-description: Onboard existing Java source code into a proper Fluent Commerce extension module. Analyzes non-standard code layouts (loose files, decompiled JARs, different build systems), restructures into Maven multi-module format with module.json, validates the result, and optionally attempts a build. Triggers on "onboard source", "refactor to module", "convert to module format", "restructure module", "import source code", "migrate to fluent module".
+name: fluent-module-convert
+description: Convert existing Java source code into a proper Fluent Commerce extension module by analyzing non-standard layouts and restructuring into Maven multi-module format. Use for converting or migrating existing code to module format.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <source-path> [--module-name <name>] [--account-prefix <PREFIX>] [--dry-run] [--skip-build]
 cursor-tier: manual
-planning-gate: advisory
+planning-gate: mandatory
 ---
 
-# Source Onboarder
+# Module Converter
 
-Take existing Java source code — whether loose files, a non-standard project layout, a decompiled JAR, or a project using a different build system — and restructure it into a proper Fluent Commerce extension module that passes `/fluent-module-validate` and builds with `/fluent-build`.
+Convert existing Java source code — whether loose files, a non-standard project layout, a decompiled JAR, a plugin, or a project using a different build system — into a proper Fluent Commerce extension module that passes `/fluent-module-validate` and builds with `/fluent-build`.
 
 ## Pre-flight: Feedback Check
 
 Before starting, check for past learnings from this skill:
 
-1. Check if `accounts/<PROFILE>/feedback/fluent-source-onboard.jsonl` exists
+1. Check if `accounts/<PROFILE>/feedback/fluent-module-convert.jsonl` exists
 2. If yes, read last 20 records
 3. Filter to: FAILURE or USER_CORRECTED outcomes, confidence = CONFIRMED or PROMOTED
 4. Extract top 3 relevant learnings — use as internal guidance during execution
@@ -25,14 +25,16 @@ Before starting, check for past learnings from this skill:
 ## When to Use
 
 - "I have Java rule classes but they're not in a Fluent module structure"
+- "Convert this existing plugin to a proper module"
 - "Onboard this decompiled JAR into a buildable module"
 - "Convert this Gradle project to Fluent Commerce module format"
 - "I have source code from another team — make it a proper module"
 - "Restructure this code into the standard Maven multi-module layout"
 - "Import these rule classes into a deployable module"
+- "Analyze this plugin and convert it to module format"
 - Code exists in `accounts/<PROFILE>/SOURCE/backend/` but doesn't pass `/fluent-module-validate`
 - Decompiled output exists in `accounts/<PROFILE>/SOURCE/backend/.decompiled/` and needs to become a buildable module
-- `/fluent-scope-plan` generated a `SOURCE_ONBOARD` task
+- `/fluent-scope-plan` generated a `MODULE_CONVERT` task
 
 ## When NOT to Use
 
@@ -88,11 +90,62 @@ This skill does **not** own:
 
 ## Execution Protocol
 
-**Phase ordering note:** Unlike most implementation skills, source-onboard runs analysis (Phase 1) BEFORE the planning gate (Phase 2). This is intentional — you must understand what exists before you can plan the restructuring. Phase 1 is read-only analysis. Phase 2 is the mandatory approval gate before any files are modified.
+**Phase ordering note:** Unlike most implementation skills, module-convert has TWO user checkpoints before any files are modified:
 
-### Phase 1: Source Analysis (read-only)
+1. **Phase 0** — Intake triage: resolve ambiguity (source path, intent, namespace, module name)
+2. **Phase 1** — Source analysis (read-only): scan, classify, present findings → **user confirms or corrects**
+3. **Phase 2** — Planning gate (mandatory): present restructuring plan → **user approves before execution**
 
-**Goal:** Understand what exists, classify its state, and identify all rule classes. **No files are modified in this phase.**
+This two-checkpoint flow is intentional. The user knows their code better than the AI — they can catch misclassified rules, wrong namespaces, or deprecated code at the analysis stage, before the plan is built on top of potentially wrong assumptions.
+
+### Phase 0: Intake Triage
+
+Before scanning any files, resolve critical unknowns. Ask these **only if the answer is not already clear** from the user's prompt, arguments, or workspace context. Do not ask questions you can answer by reading the filesystem.
+
+#### 0.1 Source Path
+
+If the user did not provide a `source-path`:
+1. Check `accounts/<PROFILE>/SOURCE/backend/` for candidate directories
+2. If exactly one candidate, confirm: _"Found `accounts/ACME/SOURCE/backend/legacy-plugin/` — convert this?"_
+3. If multiple candidates, list them and ask which one
+4. If none, ask: _"Where is the source code you want to convert? Provide a path relative to the workspace root."_
+
+#### 0.2 Intent Check
+
+If the prompt uses ambiguous language ("analyze", "look at", "check") without clear conversion intent ("convert", "restructure", "module format", "onboard"):
+- Ask: _"Do you want to **analyze** this code (understand what it does → `/fluent-custom-code`) or **convert** it into a Fluent module (restructure + build infrastructure)?"_
+
+If the source path already contains a valid `module.json` + `pom.xml` + standard Maven layout:
+- Ask: _"This already looks like a valid Fluent module. Do you want to **repair** structural issues, or **re-convert** from scratch?"_
+
+#### 0.3 Plugin Namespace (Account Prefix)
+
+The plugin namespace determines rule registration keys (e.g., `ACME.order.ValidateReturnWindow`). This MUST be correct — a wrong namespace means workflows can't find the rules at runtime.
+
+**Auto-detection order:**
+1. `--account-prefix` argument → use as-is
+2. Existing `module.json` in the source → extract from rule keys (the prefix before the first `.`)
+3. `plugin_list` from the live environment → extract common prefix from deployed rules
+4. Active profile name from CLI context
+
+**If auto-detection fails or finds conflicting prefixes**, ask:
+_"What plugin namespace should I use for rule registration? This becomes the prefix in rule keys like `<NAMESPACE>.order.ValidateReturnWindow`."_
+
+**If auto-detected prefix differs from deployed prefix**, warn and confirm:
+_"The source uses prefix `ACME` but deployed rules use `MY_COMPANY`. Which should the converted module use?"_
+- **Use deployed prefix** (recommended) — zero-disruption, workflows keep working
+- **Use source prefix** — requires workflow redeployment to update rule references
+
+#### 0.4 Module Name
+
+If `--module-name` was not provided and cannot be derived from the source directory name or existing `module.json`:
+- Ask: _"What should the module be called? This sets the Maven artifact ID and module.json name (e.g., `my-returns`)."_
+
+**Skip Phase 0 entirely** when the user provides a clear `source-path`, conversion intent, and the source contains enough context to auto-detect namespace and module name.
+
+### Phase 1: Source Analysis (read-only, results shown to user)
+
+**Goal:** Understand what exists, classify its state, and identify all rule classes. **No files are modified in this phase.** Analysis results are presented to the user at the end of this phase — the user can correct misclassifications before the plan is built.
 
 #### Step 1.1: Classify Source Layout
 
@@ -123,12 +176,19 @@ source-path/
 For each Java file found, determine if it's a Fluent rule class:
 
 **Detection patterns** (check in order):
-1. Extends `BaseRule` or `Rule` (from Rubix SDK)
+1. Extends `BaseRule` or `Rule` (from Rubix SDK) — **check transitively**: if a class extends a project-local base class (e.g., `com.puma.common.BaseRule`) that itself implements `Rule` or extends SDK `BaseRule`, treat it as a rule. Read the base class source to confirm.
 2. Has `@RuleInfo` annotation
-3. Implements `run(ContextWrapper context)` or `run(Context context)` method
-4. Contains `context.getProp(...)` or `context.getEvent()` calls
+3. Implements `run(...)` or a custom `execute(...)` method that is called from `run()` — projects often wrap the SDK `run(Context)` in a custom base class that delegates to `execute(ContextWrapper)`
+4. Contains `context.getProp(...)`, `context.getEvent()`, or equivalent calls through a project-specific context wrapper
 5. Is registered in a `module.json` (if one exists)
 
+**Custom base class / context wrapper detection:**
+Many production plugins define their own `BaseRule` and `ContextWrapper` that wrap the SDK classes. When detected:
+- Classify the custom base class as `FRAMEWORK` (not rule, not utility)
+- Move it to `plugins/util/` alongside other framework-level classes
+- Do NOT rewrite rules to use SDK classes directly — preserve the custom wrapper
+- Note the inheritance chain in the analysis output so the user can verify
+
 **For each detected rule, extract:**
 - Class name (e.g., `ValidateReturnWindow`)
 - Package name (e.g., `com.fluentcommerce.rule.order`)
@@ -143,6 +203,26 @@ For each Java file found, determine if it's a Fluent rule class:
 - Missing Javadoc/comments
 - Confidence level: decompiled vs original
 
+#### Step 1.2b: Discover Non-Java Assets
+
+Scan for non-Java files that need special handling:
+
+**GraphQL operations** (`*.graphql` files):
+- Typically in `src/main/graphql/` — used by Apollo code generation at build time
+- These must stay alongside the rules submodule (Apollo plugin wires them during compile)
+- Count mutations vs queries, note the GraphQL package path
+
+**Settings and manifest JSONs:**
+- Look for `settings/`, `manifests/`, or directories containing Mystique manifest JSON files (`fc.mystique.manifest.*`)
+- These are **NOT part of the extension module** — they belong in a separate data module
+- Flag to the user: _"Found N settings/manifest files. These should be deployed as a separate data module (`/fluent-data-module-scaffold`), not bundled with the extension module."_
+
+**Other non-Java resources:**
+- `reviewTools/`, `scripts/`, documentation, Python files — flag as non-module assets that won't be included in the restructured module
+- Config files (`.properties`, `.yml`, `.xml` other than POM) — may need to move to `src/main/resources/`
+
+Present the asset inventory in the Phase 1.5 findings so the user can decide what to include.
+
 #### Step 1.3: Detect Existing module.json
 
 If a `module.json` exists in the source path:
@@ -166,6 +246,77 @@ plugin_list (compact: true)
 - Identify rules that are deployed but have different versions or parameters
 - Flag any namespace conflicts
 
+#### Step 1.5: Present Analysis Findings
+
+**Before proceeding to the plan, present a structured summary of what was found.** This gives the user a chance to correct misclassifications, flag deprecated rules, or adjust the namespace before the restructuring plan is built on top of these findings.
+
+```markdown
+## Source Analysis — What I Found
+
+| Property | Value |
+|----------|-------|
+| Source path | `accounts/<PROFILE>/SOURCE/backend/rubix-plugin-<name>/` |
+| Layout category | MAVEN_NONSTANDARD (flat single-POM, not multi-module) |
+| Java files found | 469 |
+| Rule classes detected | 346 (across 17 domains) |
+| Framework classes | 4 (custom BaseRule, ContextWrapper, Guard, LogJsonSerializer) |
+| Model/DTO classes | 86 |
+| Service classes | 12 |
+| Utility classes | 17 |
+| Exception classes | 4 |
+| Test classes found | 126 |
+| Existing module.json | No |
+| Existing pom.xml | Yes (flat, v1.0.36) |
+| Plugin namespace | <ACCOUNT_PREFIX>.<namespace> (from POM properties) |
+
+### Non-Java Assets
+
+| Asset Type | Count | Location | Recommendation |
+|-----------|-------|----------|----------------|
+| GraphQL operations | N (.graphql files) | src/main/graphql/ | Keep with rules submodule (Apollo build-time) |
+| Mystique manifests | N JSON files | settings/UI Settings/ | **Separate data module** — not part of extension |
+| Other settings | N JSON files | settings/ | **Separate data module** |
+| Dev tooling | Scripts, docs | reviewTools/ etc. | Exclude from module (not deployable) |
+
+### Custom Framework Classes
+
+| Class | Purpose | Impact |
+|-------|---------|--------|
+| `com.<org>.common.BaseRule` | Wraps SDK `Rule`, adds execute/logging/exception pattern | **All N rules extend this** — must preserve |
+| `com.<org>.common.ContextWrapper` | Wraps SDK `Context` with convenience methods | **All rules use this** — must preserve |
+| Other framework classes | Validation, serialization, etc. | Used by rules — move to util |
+
+### Discovered Rules (top domains by count)
+
+| Domain | Rules | Entity Type | Examples |
+|--------|-------|-------------|---------|
+| order | N | ORDER | (list top 2-3 class names) |
+| fulfilment | N | FULFILMENT | (list top 2-3 class names) |
+| consignment | N | CONSIGNMENT | (list top 2-3 class names) |
+| *(+ more domains)* | N | — | — |
+
+### Issues & Decisions Needed
+
+- ⚠ **No module.json** — N rule registrations will be generated. Confirm namespace `<ACCOUNT_PREFIX>.<namespace>` is correct.
+- ⚠ **N rules have no tests** — skeletons will be generated for untested rules
+- ⚠ **Custom BaseRule wrapper** — rules extend project-local BaseRule, not SDK BaseRule. Will preserve as-is.
+- ❓ **Package rename?** Source uses `com.<org>.*`. Recommend keeping as-is for large codebases (massive import churn, no runtime benefit). Want to repackage to `com.fluentcommerce.*`?
+- ❓ **Settings/manifests** — N JSON files found. Deploy as separate data module? Or include in extension?
+- ❓ **GraphQL operations** — N `.graphql` files found. Keep with rules submodule for Apollo build? Or separate?
+
+Does this look correct? Any classes I misclassified? Any rules to exclude?
+```
+
+**Wait for the user to confirm or correct.** Common corrections:
+- _"ReturnHelper is actually a rule, not a utility"_ → reclassify
+- _"NotifyWarehouse is deprecated, exclude it"_ → remove from plan
+- _"The namespace should be MY_COMPANY, not ACME"_ → update prefix
+- _"Keep the package as com.puma"_ → skip repackaging
+- _"Yes, separate data module for settings"_ → flag for `/fluent-data-module-scaffold`
+- _"Looks good, proceed"_ → move to Phase 2
+
+If the user says nothing controversial or confirms, proceed to Phase 2. If they correct something, update the analysis and re-present if the change is significant (e.g., namespace change affects all rule keys).
+
 ### Phase 2: Planning Gate
 
 #### Pre-flight Chain (Three-Level)
@@ -177,14 +328,14 @@ Before restructuring any source code, run the three-level pre-flight check:
    - Check `plan: "APPROVED"` — If missing, BLOCK: `→ BLOCKED: PLAN_REQUIRED — Run /fluent-feature-plan first`
    - If both approved, skip to implementation referencing the plan's relevant sections
 2. **Multi-artifact work** (onboarding as part of larger feature): STOP. Invoke `/fluent-feature-plan` first
-3. **Standalone source-onboard work** (no feature context):
+3. **Standalone module-convert work** (no feature context):
    - Check `accounts/<PROFILE>/tasks/` for a task plan with `Status: APPROVED`
    - If approved task plan found, skip to implementation
    - If no plan, continue to the Planning Gate below
 
-**MANDATORY: Present a restructuring plan before making ANY changes.** Use the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill as the base structure. Every table row must carry a Source column (NEW/EXISTING/MODIFIED/REUSED/OOTB). Extend with the source-onboard-specific sections below.
+**MANDATORY: Present a restructuring plan before making ANY changes.** Use the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill as the base structure. Every table row must carry a Source column (NEW/EXISTING/MODIFIED/REUSED/OOTB). Extend with the module-convert-specific sections below.
 
-Write the plan to: `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-source-onboard-<slug>.md`. Set `Status: PENDING`.
+Write the plan to: `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-module-convert-<slug>.md`. Set `Status: PENDING`.
 
 **Source-onboard specific sections** (in addition to the standard template):
 
@@ -342,11 +493,19 @@ For each discovered rule class:
    - Classes that are rule implementations --> `plugins/rules/<alias>/src/main/java/`
 
 **Classification heuristics:**
-- Extends `BaseRule`/`Rule` or has `@RuleInfo` --> rule
+- Extends `BaseRule`/`Rule` (SDK or project-local) or has `@RuleInfo` --> rule
+- Is a custom base class that wraps SDK `Rule`/`BaseRule` (e.g., project-local `BaseRule`, `ContextWrapper`) --> **framework** (goes to `plugins/util/`)
+- Is a custom exception class --> **framework** (goes to `plugins/util/`)
 - Is an `enum`, has only getters/setters, or has `@Data`/`@Builder` --> type
 - Is a helper/utility (static methods, service patterns, no rule inheritance) --> util
+- Is a service class (dependency injection, API calls, no rule inheritance) --> util
 - Unclear --> ask user, default to rules
 
+**Package rename decision (ask in Phase 1.5 findings):**
+- If the project uses a custom package (e.g., `com.puma.*`), ask: _"The source uses package `com.puma.*`. Do you want to keep this or repackage to `com.fluentcommerce.*`?"_
+- **Recommend keeping the original** for large codebases (100+ files) — repackaging causes massive import churn with no runtime benefit
+- Only repackage if the user explicitly requests it or the package conflicts with another deployed module
+
 #### Step 3.3: Fix Common Structural Issues
 
 Apply these fixes automatically (all tracked in the plan):
@@ -473,6 +632,43 @@ plugin_list (name filter: <ACCOUNT_PREFIX>)
 | Rule key format matches deployed format | PASS/FAIL per rule |
 | Account prefix is consistent | PASS/FAIL |
 
+#### Step 4.3b: Workflow Rule Cross-Reference (like-for-like proof)
+
+The restructured module must be functionally equivalent — every rule that workflows reference must still be registered under the **exact same key**. Structure changes; behavior must not.
+
+1. **Collect rule keys** from the new `module.json` → `newKeys[]`
+2. **Collect deployed rule keys** from `plugin_list` that match the module's account prefix → `deployedKeys[]`
+3. **Download workflows** that reference any of the deployed keys:
+   ```
+   workflow_list → for each workflow:
+     workflow_get (entityType, entitySubtype)
+   ```
+4. **Extract workflow rule references**: Grep each workflow JSON for rule keys in `rulesets[].rules[].name`
+5. **Cross-reference table:**
+
+```markdown
+## Workflow Rule Cross-Reference
+
+| Rule Key | In New module.json? | In Deployed module? | Referenced In Workflows | Status |
+|----------|--------------------|--------------------|------------------------|--------|
+| MY_PROFILE.order.ValidateOrder | Yes | Yes (v2.1) | ORDER::HD (ruleset: ON_VALIDATION) | MATCH |
+| MY_PROFILE.order.CreateFulfilment | Yes | Yes (v2.1) | ORDER::HD (ruleset: FULFIL) | MATCH |
+| MY_PROFILE.webhook.NotifyWarehouse | Yes | No (new) | — | NEW (no workflow ref yet) |
+| OLD_PREFIX.order.LegacyCheck | No | Yes (v1.0) | ORDER::HD (ruleset: ON_VALIDATION) | BREAK — workflow references key not in new module |
+```
+
+6. **Verdicts:**
+   - **MATCH**: Same key in new module.json, deployed, AND workflow → safe
+   - **NEW**: In new module.json but not deployed or in workflows → safe (new rule, not yet wired)
+   - **BREAK**: In workflow but NOT in new module.json → **FAIL** — deployment would break this workflow ruleset
+   - **ORPHAN**: In new module.json but not in any workflow → WARN (registered but unused)
+
+7. **If any BREAK found:** STOP. Present the breaks to the user with the old key → new key mapping and ask whether to:
+   - Preserve the old key format in module.json (recommended for zero-disruption)
+   - Accept the key change and update the workflow JSON to match (requires workflow redeployment)
+
+**This step is the "like-for-like" proof**: if all workflow-referenced rules show MATCH, the converted module is a drop-in replacement. Deploy the module and workflows continue working without changes.
+
 #### Step 4.4: Functional Checklist
 
 Present a manual verification checklist to the user:
@@ -665,19 +861,22 @@ fc-module-ext/
 
 ```bash
 # Onboard decompiled JAR output into a module
-/fluent-source-onboard accounts/MY_PROFILE/SOURCE/backend/.decompiled/fc-module-ext/
+/fluent-module-convert accounts/MY_PROFILE/SOURCE/backend/.decompiled/fc-module-ext/
 
 # Onboard loose Java files with explicit module name
-/fluent-source-onboard ./my-rules/ --module-name my-returns
+/fluent-module-convert ./my-rules/ --module-name my-returns
 
 # Dry run — analyze and plan only, don't modify anything
-/fluent-source-onboard accounts/MY_PROFILE/SOURCE/backend/legacy-project/ --dry-run
+/fluent-module-convert accounts/MY_PROFILE/SOURCE/backend/legacy-project/ --dry-run
 
 # Onboard without attempting build (e.g., missing SDK locally)
-/fluent-source-onboard accounts/MY_PROFILE/SOURCE/backend/old-module/ --skip-build
+/fluent-module-convert accounts/MY_PROFILE/SOURCE/backend/old-module/ --skip-build
+
+# Convert an existing plugin to module format
+/fluent-module-convert accounts/MY_PROFILE/SOURCE/backend/my-legacy-plugin/
 
 # Repair an existing module with structural issues
-/fluent-source-onboard accounts/MY_PROFILE/SOURCE/backend/fluentcommerce-fc-module-ext/
+/fluent-module-convert accounts/MY_PROFILE/SOURCE/backend/fluentcommerce-fc-module-ext/
 ```
 
 ## Post-Execution: Feedback Capture
@@ -686,13 +885,13 @@ After completing this skill (whether success or failure), write a feedback recor
 
 1. **Classify outcome:** `SUCCESS` (completed cleanly), `PARTIAL_SUCCESS` (completed after fixing issues), `FAILURE` (could not complete), `BLOCKED` (prereq missing), `USER_CORRECTED` (user overrode approach)
 2. **Build record:** Create a `feedback-record-v1` JSON object with:
-   - `skill`: `"fluent-source-onboard"`
+   - `skill`: `"fluent-module-convert"`
    - `feature`: feature slug if applicable, null otherwise
    - `phases`: trace of each phase with PASS/FAIL/SKIP
    - `learnings`: any gotchas discovered during execution
    - `userCorrections`: any corrections the user provided
 3. **Redact secrets:** Strip tokens, passwords, API keys. Keep business identifiers.
-4. **Append** one JSON line to `accounts/<PROFILE>/feedback/fluent-source-onboard.jsonl`
+4. **Append** one JSON line to `accounts/<PROFILE>/feedback/fluent-module-convert.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 asked a question, no actual write operation happened).

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

@@ -1,12 +1,13 @@
 ---
 name: fluent-module-scaffold
-description: Scaffold a new Fluent Commerce extension module WITH Java plugins. Generates Maven project structure, module.json, build scripts, initial rule classes, test skeletons, and .gitignore. If the user says "no Java", "no code", "workflow-only", "JSON-only", or "data-only module", route to /fluent-data-module-scaffold instead — those are data modules, not extension modules. HARD NEGATIVE — Do NOT route here for: 'data-only module' / 'no Java' / 'no plugins' / 'workflow-only module' / 'settings-only module' / 'resources-only' (→ fluent-data-module-scaffold for modules without Java plugin code). Triggers on "scaffold module", "new module", "create module", "initialize module", "create Java module", "new extension module".
+description: Scaffold a new Fluent Commerce extension module with Java plugins, Maven structure, module.json, build scripts, and test skeletons. Use for creating new extension modules that include compiled Java code.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <module-name> [--entity-types ORDER,FULFILMENT] [--rules RuleName1,RuleName2] [--account-prefix ACCT]
 cursor-tier: manual
 planning-gate: mandatory
 ---
+<!-- routing-notes: HARD NEGATIVE — Do NOT route here for "data-only module", "no Java", "no plugins", "workflow-only module", "settings-only module", "resources-only" (→ fluent-data-module-scaffold for modules without Java plugin code). -->
 
 # Module Scaffolder
 

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

@@ -1,11 +1,12 @@
 ---
 name: fluent-module-validate
-description: MODULE INVENTORY AND STRUCTURAL VALIDATION — Discover, classify, and validate Fluent Commerce modules. Inventories all deployed modules (reference vs custom), validates extension module structure, and maps registered rules to their source. Produces cached JSON artifacts with content hashing. ROUTING PRIORITY — if the prompt says "inventory all deployed modules", "classify modules as reference vs custom", "validate extension module structure", "module health", "list modules", or "what modules are deployed", route HERE — do NOT route to fluent-implementation-map. fluent-implementation-map maps business features and flows; this skill inventories and validates module structures. Triggers on "validate module", "check module structure", "module health", "what modules are deployed", "list modules", "is my module correct", "inventory deployed modules", "classify modules", "reference vs custom".
+description: Discover, classify, and validate Fluent Commerce modules with structural checks, rule-to-source mapping, and reference-vs-custom classification. Use for module inventory, structure validation, or deployment health checks.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [module-root-path | inventory] [--fix] [--force]
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the prompt says "inventory modules", "classify modules", "validate module structure", "module health", "list modules", or "what modules are deployed", route HERE — do NOT route to fluent-implementation-map. fluent-implementation-map maps business features and flows; this skill inventories and validates module structures. -->
 
 # Module Inventory and Structure Validator
 
@@ -136,8 +137,8 @@ servicepoint, wave, returns, b2c-sample-data, b2c-sample-data-inventory
 |------|-------------|-----------|-------------|---------|
 | **REFERENCE** | Standard Fluent Commerce modules from repository. Deployed via `fluent module install <name>`. | Yes (OOTB rules) | No (closed-source) | `fluent-commerce/core`, `fluent-commerce/order` |
 | **CUSTOM_EXTENSION** | Account-specific modules with custom Rubix rules. Built from Java source. | Yes (custom rules) | Yes (under `accounts/<PROFILE>/SOURCE/backend/`) | `fluent-commerce/fc-module-custom-extension` |
-| **CUSTOM_WORKFLOW** | Workflow definitions packaged as deployable modules. | No | Workflow JSON in module ZIP | `fluent-commerce/fc-workflow-order-hm-updated` |
-| **CUSTOM_DATA** | Configuration, settings, sample data, access control. No executable rules. | No | JSON/config files in module ZIP | `HM`, `hm-inventory-data`, `hm/global-access` |
+| **CUSTOM_WORKFLOW** | Workflow definitions packaged as deployable modules. | No | Workflow JSON in module ZIP | `fluent-commerce/fc-workflow-order-acme-updated` |
+| **CUSTOM_DATA** | Configuration, settings, sample data, access control. No executable rules. | No | JSON/config files in module ZIP | `ACME`, `acme-inventory-data`, `acme/global-access` |
 
 **All types must be deployed** — even reference modules are deployed per-retailer via `fluent module install`.
 
@@ -236,10 +237,10 @@ console.log(age > 3600 ? 'stale' : 'fresh');
       }
     ],
     "customWorkflow": [
-      { "name": "fluent-commerce/fc-workflow-order-hm-updated", "version": "1.0.0" }
+      { "name": "fluent-commerce/fc-workflow-order-acme-updated", "version": "1.0.0" }
     ],
     "customData": [
-      { "name": "HM", "version": "1.0.13" }
+      { "name": "ACME", "version": "1.0.13" }
     ]
   },
   "referenceArtifacts": [
@@ -254,10 +255,10 @@ console.log(age > 3600 ? 'stale' : 'fresh');
   ],
   "undeployedModules": [
     {
-      "name": "fluent-commerce/fc-module-hm-return",
+      "name": "fluent-commerce/fc-module-acme-return",
       "version": "0.0.6",
       "moduleType": "configuration_only",
-      "sourcePath": "accounts/<PROFILE>/SOURCE/backend/fluentcommerce-fc-module-hm-return",
+      "sourcePath": "accounts/<PROFILE>/SOURCE/backend/fluentcommerce-fc-module-acme-return",
       "deploymentStatus": "not_deployed"
     }
   ],

package/content/dev/skills/fluent-mystique-assess/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-mystique-assess
-description: Validate and analyze Mystique manifest JSON. Phase 1 validates against the v2.0 schema, lints component configurations, cross-references aliases, data sources, and i18n keys. Phase 2 scores complexity, analyzes component usage patterns, i18n coverage, query efficiency, and architectural health. Produces structured reports and Mermaid diagrams. Do not use this for TypeScript/React source-code review of .ts/.tsx files; that belongs to fluent-frontend-review. Triggers on "validate manifest", "check mystique", "lint manifest", "analyze manifest", "mystique audit", "ui complexity", "manifest analysis", "component usage", "mystique health", "mystique issues".
+description: Validate and analyze Mystique manifest JSON with schema checks, complexity scoring, component usage patterns, and i18n coverage. Use for manifest validation, lint, or UI architecture health assessment.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <manifest-file-or-directory> [--validate-only] [--analyze-only] [--strict] [--fix-suggestions] [--deep] [--mermaid] [--deployed] [--component <alias>] [--profile <name>]
@@ -257,13 +257,13 @@ Exit codes: `0` = PASS (no CRITICAL/HIGH), `1` = FAIL.
 
 ### Automated Validator
 
-A Node.js linter script is available at `fluent-ai-skills/content/dev/skills/fluent-mystique-assess/validator.mjs`. **Always run this first** before manual review.
+A Node.js linter script is available at `fluent-ai-skills/tools/manifest-validator.mjs`. **Always run this first** before manual review.
 
 ```bash
-node fluent-ai-skills/content/dev/skills/fluent-mystique-assess/validator.mjs <manifest.json>
-node validator.mjs <manifest.json> --strict --fix-suggestions
-node validator.mjs <manifest.json> --component fc.list
-node validator.mjs <manifest.json> --json
+node fluent-ai-skills/tools/manifest-validator.mjs <manifest.json>
+node fluent-ai-skills/tools/manifest-validator.mjs <manifest.json> --strict --fix-suggestions
+node fluent-ai-skills/tools/manifest-validator.mjs <manifest.json> --component fc.list
+node fluent-ai-skills/tools/manifest-validator.mjs <manifest.json> --json
 ```
 
 If `--validate-only` is set, stop here and output the validation report. Otherwise continue to analysis.
@@ -665,6 +665,22 @@ Summary: 2 instances found, 1 FAIL, 1 PASS
 - **Backup**: Existing setting MUST be backed up before overwriting
 - **Approval**: User MUST explicitly approve before any setting update
 
+### Full Deploy Chain (emit after PASS when user wants to deploy)
+
+```
+/fluent-mystique-assess PASS
+    ↓
+Choose deployment method:
+  • Interactive: /fluent-settings (MCP setting_upsert with valueType JSON)
+  • Production:  /fluent-module-deploy --include settings (CLI, repeatable)
+    ↓
+/fluent-ui-test (verify rendered page matches expectations)
+    ↓
+FAIL? → /fluent-trace (diagnose why component isn't rendering)
+```
+
+**First-time app deployment?** Verify: (1) target app entity exists, (2) user has setting write permissions, (3) custom SDK bundle is hosted and accessible. See `/fluent-retailer-config` for entity setup, `/fluent-account-snapshot` for environment state.
+
 ---
 
 ## Graceful Degradation

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

@@ -1,12 +1,13 @@
 ---
 name: fluent-mystique-builder
-description: Build and edit Mystique manifest JSON definitions. Create pages, routes, component trees, data queries, and fragment compositions using the v2.0 schema. HARD NEGATIVE — if the user is asking for a preview, mockup, visual approval, static mock, or 'show me how it would look before we build', route to fluent-mystique-preview instead. This skill owns real manifest authoring, not pre-build visual approval. Triggers on "build manifest", "create mystique page", "add route", "mystique component", "edit manifest", "build ui", "add page to manifest".
+description: Build and edit Mystique manifest JSON definitions with pages, routes, component trees, data queries, and fragment compositions using the v2.0 schema. Use for manifest authoring or editing UI configuration.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <operation> [manifest-file] [--page <path>] [--section <name>] [--fragment]
 cursor-tier: manual
 planning-gate: mandatory
 ---
+<!-- routing-notes: HARD NEGATIVE — if the user asks for a preview, mockup, visual approval, or "show me how it would look before we build", route to fluent-mystique-preview instead. This skill owns real manifest authoring, not pre-build visual approval. -->
 
 # Mystique Manifest Builder
 
@@ -369,6 +370,36 @@ Before building a manifest that references custom SDK components (non-`fc.*` ali
 
 Understanding how manifests and custom components reach users is critical for correct builder output.
 
+### New App Prerequisites
+
+When building a manifest for a brand-new Fluent UX App (not modifying an existing one), verify these prerequisites before building:
+
+1. **Spec exists (recommended)** — Check `accounts/<PROFILE>/features/<slug>/status.json` for `spec: "APPROVED"`. If no spec exists, recommend `/fluent-use-case-discover` to gather requirements first, or get explicit user acknowledgment to skip. The `fluent-frontend-dev` agent enforces this as a gate at Phase 1.5.
+2. **App entity exists** — The target app (OMS, Store, or custom) must exist in the environment. Check with `/fluent-account-snapshot` or MCP `entity_get`.
+3. **Setting namespace available** — Root manifests use `fc.mystique.manifest.<app-name>`. Confirm no existing setting conflicts. Fragments use `fc.mystique.manifest.<app-name>.<section>`.
+4. **Permissions** — The deploying user/role needs permission to create settings with `context: "ACCOUNT"`, `contextId: 0`. See `knowledge/platform/roles-and-permissions.md` for the three-layer access control model (platform permissions, custom roles, manifest-based visibility).
+5. **Plugin hosting** — If using custom SDK components, the bundle hosting URL must be accessible from end-user browsers. Localhost is fine for development only.
+
+If any prerequisite is missing, recommend: `/fluent-use-case-discover` (gather requirements), `/fluent-retailer-config` (create entities), `/fluent-settings` (manage settings), `/fluent-mystique-scaffold` (set up SDK project).
+
+### Full New App Sequence
+
+For building a complete new Mystique app end-to-end, follow this lifecycle. Each step can be skipped if scope is clear and user acknowledges:
+
+```
+1. /fluent-use-case-discover  → Gather requirements (UI pages, roles, entities, data queries)
+2. /fluent-feature-plan       → Plan with frontend architecture (route map, component tree, settings)
+3. /fluent-mystique-builder   → Create root manifest + fragments (this skill, Operation 1)
+4. /fluent-mystique-scaffold  → Scaffold SDK project (only if custom components needed)
+5. /fluent-mystique-assess    → Validate manifest (49 rules, 6 phases — 0 CRITICAL/HIGH to proceed)
+6. /fluent-mystique-preview   → Visual preview in browser (optional but recommended)
+7. /fluent-frontend-build     → Build SDK bundle (7 gates — only if SDK project exists)
+8. Deploy manifest            → Via GraphQL createSetting or CLI module install (see Safety Guardrails below)
+9. /fluent-ui-test            → Verify in browser (login, navigate, render, user actions, roles)
+```
+
+The `fluent-frontend-dev` agent orchestrates this entire sequence with gates at Phase 1.5 (spec), Phase 2 (plan approval), Phase 4 (validation), and Phase 5 (deploy safety).
+
 ### Manifests are JSON Configuration
 
 Manifests are pure JSON — they are NOT compiled or bundled. They are deployed to Fluent UX Apps through one of:
@@ -852,7 +883,7 @@ Every Mystique manifest follows this top-level structure:
 | `plugins` | `MystiquePlugin[]` | `[]` | External component bundle URLs or setting references |
 | `orchestrationAlias` | `string` | none | Overrides the `module` value the app sends to the Transition API. OMS App uses `"adminconsole"` so `modules: ["adminconsole"]` in workflow user actions. Store App uses `"servicepoint"` as its orchestration alias (distinct from the manifest setting name `fc.mystique.manifest.store`). |
 
-**Store App context & location switching:** When `context.level` is `"location"`, the app scopes all queries to the active location. Set `"switcher": true` and `"role": ["STORE", "STORE_ASSISTANT"]` to enable the OOTB location dropdown. The switcher only appears when the user has roles at multiple locations. Location is persisted in `localStorage["mystique.auth.context.location"]` (stores ID, not ref). Deep-link to a specific location with `?user.location.ref=<LOC_REF>` after the hash path. See `knowledge/platform/mystique-routing.md` §"Store App — Default Location via URL Parameter" for full resolution order and permission enforcement.
+**Context switching (Store + OMS):** When `context.level` is `"location"` (Store) or `"retailer"` (OMS), the app scopes queries to the active context. Set `"switcher": true` and the appropriate `"role"` array to enable the OOTB dropdown. The switcher only appears when the user has roles at multiple contexts. Context is persisted in `localStorage` — `mystique.auth.context.location` (Store, stores ID) or `mystique.auth.context.retailer` (OMS, stores ID). Deep-link with `?user.location.ref=<REF>` (Store) or `?user.retailer.ref=<REF>` (OMS) after the hash path. See `knowledge/platform/mystique-routing.md` §"Context Switching" for full resolution order and permission enforcement.
 
 ### Route Types
 

package/content/dev/skills/fluent-mystique-component/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-mystique-component
-description: Add new components, form fields, or template helpers to an existing Mystique SDK project. Generates component files, registers with the appropriate registry, and wires into the build. Triggers on "add component", "new component", "extend sdk", "add field", "new mystique component".
+description: Add new components, form fields, or template helpers to an existing Mystique SDK project with file generation, registry wiring, and build integration. Use for extending an existing SDK project with new components.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: <ComponentName> [--project <project-path>] [--type component|field|template] [--category content|layout|page|filter]

package/content/dev/skills/fluent-mystique-diff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-mystique-diff
-description: Compare Mystique manifest settings against CDN baselines. Shows which fragments are customized, which use CDN default, which are account-only, and structural diffs (routes, components, queries, plugins). Classifies OOTB vs custom components. All analysis runs locally to minimize token usage. Triggers on "manifest diff", "compare manifests", "cdn vs custom", "manifest baseline", "what's customized", "component inventory".
+description: Compare Mystique manifest settings against CDN baselines showing customized fragments, CDN defaults, account-only additions, and OOTB vs custom component classification. Use for manifest diff or CDN baseline comparison.
 user-invocable: true
 allowed-tools: Bash, Read, Write, Glob, Grep
 argument-hint: --profile <PROFILE> [--app oms|store] [--deep] [--components] [--verbose] [--refresh-cdn]

package/content/dev/skills/fluent-mystique-preview/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: fluent-mystique-preview
-description: "Mock, modify, and preview Mystique UI components in the live Fluent Commerce app before building or deploying. Three modes: ADD (inject new), MODIFY (alter existing), REMOVE (preview without). Highlights all changes with color-coded borders and badges. Supports iterative refinement. ROUTING PRIORITY — if the user asks for a preview, mockup, visual approval, static mock, or 'show me how it would look before we build', route HERE instead of fluent-mystique-builder. This skill owns pre-build visual approval, not real manifest authoring. Triggers on \"preview UI\", \"mock component\", \"preview manifest\", \"how will it look\", \"show me the UI\", \"preview in OMS\", \"preview in store\", \"visual preview\", \"UI mockup\", \"what would it look like if\", \"preview change\", \"modify the page\", \"static mockup\", \"before we build\"."
+description: Mock, modify, and preview Mystique UI components in the live Fluent Commerce app before building or deploying with ADD, MODIFY, and REMOVE modes. Use for visual previews, UI mockups, or pre-build approval.
 user-invocable: true
 read-only: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: "[--mode add|modify|remove] [--app oms|store|servicepoint] [--route /orders] [--manifest <path>] [--component <alias>] [--feature <slug>]"
 cursor-tier: manual
 ---
+<!-- routing-notes: ROUTING PRIORITY — if the user asks for a preview, mockup, visual approval, static mock, or "show me how it would look before we build", route HERE instead of fluent-mystique-builder. This skill owns pre-build visual approval, not real manifest authoring. -->
 
 # Mystique UI Preview & Iteration
 
@@ -1008,7 +1009,7 @@ When a preview is approved, add a visual reference to the feature plan:
 
 #### Embedding in feature dashboard
 
-The dashboard generator (`fluent-ai-skills/tools/generate-feature-dashboard.mjs`) can detect preview reports and embed the flip widget:
+The dashboard generator (`fluent-ai-skills/tools/feature-dashboard.mjs`) can detect preview reports and embed the flip widget:
 
 ```javascript
 // In buildDetailPanel, check for preview report
@@ -1167,6 +1168,22 @@ The approved preview report becomes the visual reference:
 - Width/positioning decided
 - **Change manifest** — exact list of ADD/MODIFY/REMOVE operations to implement
 
+### Full Deploy Chain After Approval
+
+```
+Preview APPROVED
+    ↓
+/fluent-mystique-builder   (build manifest matching approved preview)
+    ↓
+/fluent-mystique-assess    (validate manifest structure before deploy)
+    ↓
+/fluent-settings or /fluent-module-deploy   (deploy manifest as setting)
+    ↓
+/fluent-ui-test            (verify live page matches preview)
+```
+
+If custom SDK components are needed (non-`fc.*` aliases in the preview), insert `/fluent-mystique-scaffold` before the builder step.
+
 ### Verification via `/fluent-ui-test`
 
 After the real manifest is built and deployed, `/fluent-ui-test` can compare the live page against the approved preview screenshots to verify visual fidelity.