@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/rfl/skills/fluent-rfl-assess/SKILL.md

@@ -1,172 +1,172 @@
----
-name: fluent-rfl-assess
-description: Run a Ready For Launch (RFL) assessment on a Fluent Commerce implementation. Analyzes workflows, rules, settings, and integrations for production readiness. Triggers on "rfl assessment", "ready for launch check", "go-live readiness", "production audit".
-user-invocable: true
-allowed-tools: Bash, Read, Write, Edit, Glob, Grep
-argument-hint: [--profile name] [--retailer ref]
----
-
-# RFL Assessment
-
-Comprehensive Ready For Launch assessment for Fluent Commerce implementations.
-
-## When to Use
-
-- Pre-go-live production readiness check
-- Post-implementation quality review
-- Periodic health check of running implementations
-- New team member onboarding (understand current state)
-
-## Assessment Workflow
-
-### Step 1: Environment Discovery
-
-```bash
-# Verify connection
-fluent profile active
-
-# List workflows
-fluent workflow list -p <profile> -r <retailer>
-
-# List installed modules
-fluent module list -p <profile>
-```
-
-### Step 2: Workflow Analysis
-
-For each workflow:
-- Download and parse workflow JSON
-- Check naming conventions
-- Detect duplicate rulesets
-- Identify orphaned rulesets
-- Verify state transitions are complete
-- Check for cyclic dependencies
-
-### Step 3: Custom Rules Review
-
-- Locate plugin source code under `accounts/<PROFILE>/SOURCE/`
-- If source is unavailable:
-  - Check for JARs or decompiled output at `accounts/<PROFILE>/SOURCE/.decompiled/`
-  - If neither exists, run `/fluent-custom-code <PROFILE>` to decompile available JARs
-  - If no JARs are available, run `/fluent-connect` for full workspace preparation including JAR provision guidance
-  - Fall back to `plugin.list` for description-level review (rule parameters, accepted entity types, produced events) — note reduced confidence in the report
-- Analyze Java code quality (original source = high confidence; decompiled = medium confidence, note synthetic variable names)
-- Check GraphQL usage patterns
-- Verify error handling
-- Assess test coverage (skip if only decompiled source available)
-
-### Step 4: Configuration Audit
-
-- Query settings via GraphQL
-- Check user and role setup
-- Verify catalogue configuration
-- Validate network topology
-- Confirm location setup
-
-### Step 5: Generate Report
-
-Output: `rfl-report-<retailer>-<timestamp>.md`
-
-Includes:
-- Overall score (0-100)
-- Risk matrix
-- Findings by category
-- Prioritized recommendations
-- Go/No-Go recommendation
-
-## Scoring
-
-| Score | Rating | Meaning |
-|-------|--------|---------|
-| 90-100 | Excellent | Ready for launch |
-| 75-89 | Good | Minor issues, safe to launch |
-| 60-74 | Fair | Address high-priority items first |
-| 40-59 | Poor | Significant work needed |
-| 0-39 | Critical | Not ready for launch |
-
-## Common Findings
-
-| Category | Finding | Severity |
-|----------|---------|----------|
-| Workflow | Orphaned rulesets | Medium |
-| Workflow | Missing error handlers | High |
-| Rules | No test coverage | High |
-| Rules | Hardcoded values | Medium |
-| Config | Missing settings | Critical |
-| Integration | No retry on webhook failure | High |
-
-## Event Health Assessment
-
-As part of the RFL assessment, check event processing health:
-
-Prerequisites:
-- Metrics queries require a user/token with `METRICS_VIEW`.
-- Interpret metrics as trend-level observability signals (Prometheus functions may extrapolate around scrape windows), not ledger-accurate financial totals.
-
-### Automated Health Check (Preferred)
-```
-metrics.healthCheck({
-  "window": "168h",
-  "topN": 20,
-  "thresholds": { "failureRate": 2, "pendingRate": 5 }
-})
-```
-Single call covers failure rate, NO_MATCH, PENDING, and dominance checks. Use stricter thresholds (2% failure) for go-live readiness.
-
-If Prometheus is unavailable, the tool automatically falls back to Event API aggregation.
-
-### Manual Checks (Drill-Down)
-
-Use these for targeted investigation when healthCheck reports findings:
-
-### Failed Events Check
-```
-event.list({
-  "eventStatus": "FAILED",
-  "from": "<last_7_days>",
-  "count": 50
-})
-```
-Flag: >5% failure rate indicates systemic issues requiring investigation before launch.
-
-### NO_MATCH Events Check
-```
-event.list({
-  "eventStatus": "NO_MATCH",
-  "from": "<last_7_days>",
-  "count": 50
-})
-```
-Flag: Any NO_MATCH events indicate missing workflow configuration (event name doesn't match any ruleset).
-
-### Exception Events Check
-```
-event.list({
-  "category": "exception",
-  "from": "<last_7_days>",
-  "count": 50
-})
-```
-Flag: Recurring exceptions with the same `lastRule` or `lastRuleSet` indicate a code-level bug.
-
-### Event Volume Analytics
-
-**Prometheus (preferred):**
-```
-metrics.query({
-  "query": "sum by (event_name, entity_type, status) (increase(rubix_event_runtime_seconds_count[24h]))",
-  "type": "instant"
-})
-```
-
-**Fallback (Event API aggregation):**
-```
-metrics.topEvents({
-  "from": "<last_24h>",
-  "topN": 20
-})
-```
-Review top events for unexpected patterns: high failure rates, unusual entity type distribution, missing expected events.
-
-For detailed event diagnostics → `/fluent-trace`.
-For monitoring workflows and anomaly detection → `/fluent-system-monitoring`.
+---
+name: fluent-rfl-assess
+description: Run a Ready For Launch (RFL) assessment on a Fluent Commerce implementation. Analyzes workflows, rules, settings, and integrations for production readiness. Triggers on "rfl assessment", "ready for launch check", "go-live readiness", "production audit".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: [--profile name] [--retailer ref]
+---
+
+# RFL Assessment
+
+Comprehensive Ready For Launch assessment for Fluent Commerce implementations.
+
+## When to Use
+
+- Pre-go-live production readiness check
+- Post-implementation quality review
+- Periodic health check of running implementations
+- New team member onboarding (understand current state)
+
+## Assessment Workflow
+
+### Step 1: Environment Discovery
+
+```bash
+# Verify connection
+fluent profile active
+
+# List workflows
+fluent workflow list -p <profile> -r <retailer>
+
+# List installed modules
+fluent module list -p <profile>
+```
+
+### Step 2: Workflow Analysis
+
+For each workflow:
+- Download and parse workflow JSON
+- Check naming conventions
+- Detect duplicate rulesets
+- Identify orphaned rulesets
+- Verify state transitions are complete
+- Check for cyclic dependencies
+
+### Step 3: Custom Rules Review
+
+- Locate plugin source code under `accounts/<PROFILE>/SOURCE/`
+- If source is unavailable:
+  - Check for JARs or decompiled output at `accounts/<PROFILE>/SOURCE/.decompiled/`
+  - If neither exists, run `/fluent-custom-code <PROFILE>` to decompile available JARs
+  - If no JARs are available, run `/fluent-connect` for full workspace preparation including JAR provision guidance
+  - Fall back to `plugin.list` for description-level review (rule parameters, accepted entity types, produced events) — note reduced confidence in the report
+- Analyze Java code quality (original source = high confidence; decompiled = medium confidence, note synthetic variable names)
+- Check GraphQL usage patterns
+- Verify error handling
+- Assess test coverage (skip if only decompiled source available)
+
+### Step 4: Configuration Audit
+
+- Query settings via GraphQL
+- Check user and role setup
+- Verify catalogue configuration
+- Validate network topology
+- Confirm location setup
+
+### Step 5: Generate Report
+
+Output: `rfl-report-<retailer>-<timestamp>.md`
+
+Includes:
+- Overall score (0-100)
+- Risk matrix
+- Findings by category
+- Prioritized recommendations
+- Go/No-Go recommendation
+
+## Scoring
+
+| Score | Rating | Meaning |
+|-------|--------|---------|
+| 90-100 | Excellent | Ready for launch |
+| 75-89 | Good | Minor issues, safe to launch |
+| 60-74 | Fair | Address high-priority items first |
+| 40-59 | Poor | Significant work needed |
+| 0-39 | Critical | Not ready for launch |
+
+## Common Findings
+
+| Category | Finding | Severity |
+|----------|---------|----------|
+| Workflow | Orphaned rulesets | Medium |
+| Workflow | Missing error handlers | High |
+| Rules | No test coverage | High |
+| Rules | Hardcoded values | Medium |
+| Config | Missing settings | Critical |
+| Integration | No retry on webhook failure | High |
+
+## Event Health Assessment
+
+As part of the RFL assessment, check event processing health:
+
+Prerequisites:
+- Metrics queries require a user/token with `METRICS_VIEW`.
+- Interpret metrics as trend-level observability signals (Prometheus functions may extrapolate around scrape windows), not ledger-accurate financial totals.
+
+### Automated Health Check (Preferred)
+```
+metrics.healthCheck({
+  "window": "168h",
+  "topN": 20,
+  "thresholds": { "failureRate": 2, "pendingRate": 5 }
+})
+```
+Single call covers failure rate, NO_MATCH, PENDING, and dominance checks. Use stricter thresholds (2% failure) for go-live readiness.
+
+If Prometheus is unavailable, the tool automatically falls back to Event API aggregation.
+
+### Manual Checks (Drill-Down)
+
+Use these for targeted investigation when healthCheck reports findings:
+
+### Failed Events Check
+```
+event.list({
+  "eventStatus": "FAILED",
+  "from": "<last_7_days>",
+  "count": 50
+})
+```
+Flag: >5% failure rate indicates systemic issues requiring investigation before launch.
+
+### NO_MATCH Events Check
+```
+event.list({
+  "eventStatus": "NO_MATCH",
+  "from": "<last_7_days>",
+  "count": 50
+})
+```
+Flag: Any NO_MATCH events indicate missing workflow configuration (event name doesn't match any ruleset).
+
+### Exception Events Check
+```
+event.list({
+  "category": "exception",
+  "from": "<last_7_days>",
+  "count": 50
+})
+```
+Flag: Recurring exceptions with the same `lastRule` or `lastRuleSet` indicate a code-level bug.
+
+### Event Volume Analytics
+
+**Prometheus (preferred):**
+```
+metrics.query({
+  "query": "sum by (event_name, entity_type, status) (increase(rubix_event_runtime_seconds_count[24h]))",
+  "type": "instant"
+})
+```
+
+**Fallback (Event API aggregation):**
+```
+metrics.topEvents({
+  "from": "<last_24h>",
+  "topN": 20
+})
+```
+Review top events for unexpected patterns: high failure rates, unusual entity type distribution, missing expected events.
+
+For detailed event diagnostics → `/fluent-trace`.
+For monitoring workflows and anomaly detection → `/fluent-system-monitoring`.

package/docs/CAPABILITY_MAP.md

@@ -1,77 +1,106 @@
-# Capability Ownership Map
-
-This document defines which command/skill is the source of truth for each capability.
-
-Use it to avoid duplicate guidance and conflicting instructions.
-
-## Ownership Table
-
-| Capability | Owner | Why |
-|---|---|---|
-| Automated diagnostics and guarded deploy execution | `flow-run` (`bin/cli.mjs`) | Deterministic checks + JSON report + explicit safety gates |
-| Manual module deployment steps | `content/cli/skills/fluent-module-deploy/SKILL.md` | Human-guided deployment with operator decisions |
-| Workflow operations (list, download, merge, workflowlog) | `content/cli/skills/fluent-workflow/SKILL.md` | Operational CLI source of truth |
-| Fluent CLI settings inspection (`fluent setting list/get`) | `content/cli/skills/fluent-cli-settings/SKILL.md` | Canonical CLI guidance for reading/auditing settings in profile+retailer context |
-| Fluent CLI retailer lifecycle (`fluent retailer create/list`) | `content/cli/skills/fluent-cli-retailer/SKILL.md` | Canonical CLI guidance for retailer bootstrap and context validation |
-| Fluent CLI MCP setup and CI/CD guarded deploy patterns | `content/cli/skills/fluent-cli-mcp-cicd/SKILL.md` | Canonical CLI guidance for `fluent mcp server --stdio` setup and pipeline-safe deploy flow |
-| Fluent CLI cross-family routing | `content/cli/skills/fluent-cli-index/SKILL.md` | Single entry point for broad or mixed Fluent CLI requests |
-| Complete CLI command reference (all subcommands + flags) | `content/cli/skills/fluent-cli-reference/SKILL.md` | Canonical reference for every Fluent CLI command, flag, and option |
-| Workflow design patterns and validation checklist | `content/dev/skills/fluent-workflow-builder/SKILL.md` | Architecture/design guidance for new workflow behavior |
-| Build, version bump, package steps | `content/dev/skills/fluent-build/SKILL.md` | Code/module build lifecycle ownership |
-| Event tracing and diagnostic decision trees | `content/dev/skills/fluent-trace/SKILL.md` | Investigation workflow ownership |
-| Event API model, types, categories, query patterns, event contracts, causality analysis, integration patterns | `content/dev/skills/fluent-event-api/SKILL.md` | Event data model knowledge, filter parameters, event contracts (pre-send validation), causality tracing patterns (`sourceEvents`, `rootEntityRef`, cross-entity chains), and common integration event patterns (inventory, PIM, WMS, carrier) |
-| Aggregate platform observability and metrics anomaly triage | `content/dev/skills/fluent-system-monitoring/SKILL.md` | Prometheus/Event API aggregate monitoring, threshold checks, and incident triage routing |
-| Opaque rule logic analysis (source request + JAR decompile fallback) | `content/dev/skills/fluent-trace/SKILL.md` + `docs/DEV_WORKFLOW.md` | Ensures workflow explanations are grounded in executable rule behavior |
-| E2E scenario patterns and polling strategy | `content/dev/skills/fluent-e2e-test/SKILL.md` | Scenario-driven behavior verification |
-| Workflow structural analysis and dependency mapping | `content/dev/skills/fluent-workflow-analyzer/SKILL.md` | Status graph, event chain tracing, orphan detection |
-| Custom source-code understanding and reusable artifact output | `content/dev/skills/fluent-custom-code/SKILL.md` | Source-map, workflow-rule-map, constraints, behavior-map, extension-plan |
-| Transition API user action discovery | `content/dev/skills/fluent-transition-api/SKILL.md` | Runtime user action queries, attribute mapping for events |
-| Test data discovery and payload generation | `content/dev/skills/fluent-test-data/SKILL.md` | Discover retailer environment (locations, products, catalogues, inventory) and generate valid test entity creation payloads dynamically |
-| Settings management | `content/dev/skills/fluent-settings/SKILL.md` | Manage retailer settings — discover, audit against workflows, create/update, migrate between environments |
-| Retailer environment configuration | `content/dev/skills/fluent-retailer-config/SKILL.md` | Configure retailer environments — create locations, networks, catalogues, inventory, carriers via GraphQL |
-| Module inventory, classification, and structure validation | `content/dev/skills/fluent-module-validate/SKILL.md` | Inventory all deployed modules (reference vs custom), classify by symbolic name, validate custom extension structure; cached JSON artifacts |
-| OOTB-vs-custom rule decision | `content/dev/skills/fluent-rule-scaffold/SKILL.md` | Pre-scaffolding check: search registered rules via plugin.list, recommend OOTB if match exists, scaffold custom only when needed |
-| MCP extension tool reference (syntax/limits) | `content/mcp-extn/skills/fluent-mcp-tools/SKILL.md` | Canonical tool-level reference |
-| MCP core setup and GraphQL core utilities | `content/mcp-official/skills/fluent-mcp-core/SKILL.md` | Canonical official MCP server reference |
-| Account connection, workspace discovery, JAR decompilation, and cached state | `content/cli/skills/fluent-connect/SKILL.md` | Guided onboarding — discovers profiles, wires MCP, downloads workflows, decompiles JARs, builds rule inventory, persists workspace state |
-| Complete account bootstrap (profile, retailer, modules, sample data) | `content/cli/skills/fluent-bootstrap/SKILL.md` | End-to-end account setup wizard with planning gate |
-| CLI profile lifecycle (create, switch, list, export, update) | `content/cli/skills/fluent-profile/SKILL.md` | Profile CRUD, active context, Postman export |
-| Ready For Launch production readiness assessment | `content/rfl/skills/fluent-rfl-assess/SKILL.md` | Scored go-live audit across workflows, rules, settings, integrations |
-| Connection topology, cross-entity dependency maps, static-vs-dynamic runtime diffs, webhook/setting conformance | `content/dev/skills/fluent-connection-analysis/SKILL.md` | Topology analysis, orphan detection, process flow classification, --validate mode for runtime coverage comparison, settings conformance inventories |
-| JOB/BATCH entity lifecycle diagnostics and monitoring | `content/dev/skills/fluent-job-batch/SKILL.md` | JOB/BATCH orchestration lifecycle, batch ingestion monitoring, job status tracking |
-| Session change tracking and audit reporting (text + JSON) | `content/dev/skills/fluent-session-summary/SKILL.md` | Running change log of all write operations; structured summary on demand; lightweight JSON export |
-| Module skeleton scaffolding (Maven, POMs, module.json, rules) | `content/dev/skills/fluent-module-scaffold/SKILL.md` | New-vs-extend decision tree; generates buildable module under `accounts/<PROFILE>/SOURCE/` |
-| Scope document decomposition into task lists | `content/dev/skills/fluent-scope-decompose/SKILL.md` | Parses ADD scope docs into ordered tasks with dependency DAG, skill mappings, ambiguity flags |
-| Version lifecycle (read, bump, sync, tag) | `content/dev/skills/fluent-version-manage/SKILL.md` | Semver bumps across POM files, module.json, CHANGELOG; git tag creation |
-| Pre-deployment quality gates | `content/dev/skills/fluent-pre-deploy-check/SKILL.md` | 26 gates across 8 phases; blocks deployment on critical failures |
-| Machine-readable compliance audit export | `content/dev/skills/fluent-session-audit-export/SKILL.md` | JSON audit trail with traceability matrix, rollback commands, compliance metadata |
-| Feature reverse-engineering and architecture documentation | `content/dev/skills/fluent-feature-explain/SKILL.md` | Synthesizes workflow, code, connection, and runtime analysis into a persisted Feature Architecture Document with Mermaid diagrams. Tiered evidence: plugin.list (always) → decompiled JAR / original source → runtime. Auto-discovers entities for runtime, decompiles JARs when no source. Includes Analysis Confidence section with per-rule evidence levels. |
-| Feature implementation planning (multi-artifact) | `content/dev/skills/fluent-feature-plan/SKILL.md` | Produces comprehensive 18-section feature plans with universal NEW/EXISTING/MODIFIED/REUSED/OOTB Source classification across all artifacts (rules, rulesets, statuses, settings, webhooks, GraphQL ops, cross-entity impacts). For NEW rules: pseudo logic contract. For OOTB: prop configuration. Template at `PLAN_TEMPLATE.md` (sibling file in skill directory). |
-| Source code onboarding into Fluent module format | `content/dev/skills/fluent-source-onboard/SKILL.md` | Restructures non-standard Java source (loose files, decompiled JARs, Gradle projects, partial modules) into Maven multi-module Fluent extension module format. Validates with module-validate, attempts build, reconciles against deployed rules. |
-| Workflow deployment (upload, validation, versioning, rollback) | `content/dev/skills/fluent-workflow-deploy/SKILL.md` | MCP `workflow.upload` primary, REST API fallback, CLI last resort; planning gate, dry-run validation, module dependency checks |
-| Data module scaffolding (no Java, assets only) | `content/dev/skills/fluent-data-module-scaffold/SKILL.md` | Scaffolds data modules with 14 asset directories, module.json, config template with prefix system, build scripts |
-| Mermaid diagram syntax validation | `content/dev/skills/fluent-mermaid-validate/SKILL.md` | Internal validator called by diagram-generating skills; pitfall tables for stateDiagram-v2, sequenceDiagram, flowchart, erDiagram |
-
-## Reconciliation Rules
-
-- Event API source docs are selectively extracted into skills; do not mirror full product docs.
-- If deployment logic changes, update `flow-run` and `fluent-module-deploy`; link from `fluent-build` rather than duplicating deploy instructions.
-- If workflow command syntax changes, update `fluent-workflow`; `fluent-workflow-builder` should reference it for operational steps.
-- If MCP tool contracts change, update `fluent-mcp-tools` first; other skills should reference it for request syntax and limits.
-- If workflow/ruleset intent is ambiguous, escalate to source/decompile flow owned by `fluent-trace` + `DEV_WORKFLOW.md` before making behavioral claims.
-- If module structure checks change, update `fluent-module-validate` first; `fluent-build` and `fluent-module-deploy` should read the cached report rather than duplicating checks.
-- Keep skill files focused on decision logic and patterns; keep low-level command/tool reference centralized.
-
-## Round-Robin Debugging Protocol
-
-| Entry intent | Route to | Avoid |
-|---|---|---|
-| "What actions are available at this status?" | `fluent-transition-api` | Re-implementing transition discovery in other skills |
-| "How do events/filters/causality work?" | `fluent-event-api` | Running full root-cause workflow here |
-| "How do I call this MCP tool?" | `fluent-mcp-tools` | Redefining tool contracts per skill |
-| "Run workflow end-to-end validation" | `fluent-e2e-test` | Duplicating trace decision trees |
-| "Why did this fail / entity stuck?" | `fluent-trace` | Repeating generic setup when failure context is already known |
-| "Explain feature / how does X work / document this flow" | `fluent-feature-explain` | Running individual analysis skills without synthesizing into a document |
-| "Plan this feature / implement curbside / design the return flow" | `fluent-feature-plan` | Using individual skills without a comprehensive plan first |
-
-Handoff rule: when E2E fails, pass `entityRef`, `entityType`, `eventId` (if available), and expected vs actual status to `fluent-trace`.
+# Capability Ownership Map
+
+This document defines which command/skill is the source of truth for each capability.
+
+Use it to avoid duplicate guidance and conflicting instructions.
+
+## Ownership Table
+
+| Capability | Owner | Why |
+|---|---|---|
+| Automated diagnostics and guarded deploy execution | `flow-run` (`bin/cli.mjs`) | Deterministic checks + JSON report + explicit safety gates |
+| Manual module deployment steps | `content/cli/skills/fluent-module-deploy/SKILL.md` | Human-guided deployment with operator decisions |
+| Workflow operations (list, download, merge, workflowlog) | `content/cli/skills/fluent-workflow/SKILL.md` | Operational CLI source of truth |
+| Fluent CLI settings inspection (`fluent setting list/get`) | `content/cli/skills/fluent-cli-settings/SKILL.md` | Canonical CLI guidance for reading/auditing settings in profile+retailer context |
+| Fluent CLI retailer lifecycle (`fluent retailer create/list`) | `content/cli/skills/fluent-cli-retailer/SKILL.md` | Canonical CLI guidance for retailer bootstrap and context validation |
+| Fluent CLI MCP setup and CI/CD guarded deploy patterns | `content/cli/skills/fluent-cli-mcp-cicd/SKILL.md` | Canonical CLI guidance for `fluent mcp server --stdio` setup and pipeline-safe deploy flow |
+| Fluent CLI cross-family routing | `content/cli/skills/fluent-cli-index/SKILL.md` | Single entry point for broad or mixed Fluent CLI requests |
+| Complete CLI command reference (all subcommands + flags) | `content/cli/skills/fluent-cli-reference/SKILL.md` | Canonical reference for every Fluent CLI command, flag, and option |
+| Account bootstrap (profile, retailer, MCP, workflows, source) | `content/cli/skills/fluent-bootstrap/SKILL.md` | Complete Fluent Commerce account bootstrap wizard with mandatory planning gate |
+| CLI profile management (create, switch, list, export) | `content/cli/skills/fluent-profile/SKILL.md` | Manage Fluent CLI profiles for connecting to Fluent Commerce accounts |
+| Ready For Launch (RFL) assessment | `content/rfl/skills/fluent-rfl-assess/SKILL.md` | Production readiness audit across workflows, rules, settings, and architecture |
+| Workflow design patterns and validation checklist | `content/dev/skills/fluent-workflow-builder/SKILL.md` | Architecture/design guidance for new workflow behavior |
+| Build, version bump, package steps | `content/dev/skills/fluent-build/SKILL.md` | Code/module build lifecycle ownership |
+| Event tracing and diagnostic decision trees | `content/dev/skills/fluent-trace/SKILL.md` | Investigation workflow ownership |
+| Event API model, types, categories, query patterns, event contracts, causality analysis, integration patterns | `content/dev/skills/fluent-event-api/SKILL.md` | Event data model knowledge, filter parameters, event contracts (pre-send validation), causality tracing patterns (`sourceEvents`, `rootEntityRef`, cross-entity chains), and common integration event patterns (inventory, PIM, WMS, carrier) |
+| Aggregate platform observability and metrics anomaly triage | `content/dev/skills/fluent-system-monitoring/SKILL.md` | Prometheus/Event API aggregate monitoring, threshold checks, and incident triage routing |
+| Opaque rule logic analysis (source request + JAR decompile fallback) | `content/dev/skills/fluent-trace/SKILL.md` + `docs/DEV_WORKFLOW.md` | Ensures workflow explanations are grounded in executable rule behavior |
+| E2E scenario patterns and polling strategy | `content/dev/skills/fluent-e2e-test/SKILL.md` | Scenario-driven behavior verification |
+| Workflow structural analysis and dependency mapping | `content/dev/skills/fluent-workflow-analyzer/SKILL.md` | Status graph, event chain tracing, orphan detection |
+| Custom source-code understanding and reusable artifact output | `content/dev/skills/fluent-custom-code/SKILL.md` | Source-map, workflow-rule-map, constraints, behavior-map, extension-plan |
+| Transition API user action discovery | `content/dev/skills/fluent-transition-api/SKILL.md` | Runtime user action queries, attribute mapping for events |
+| Test data discovery and payload generation | `content/dev/skills/fluent-test-data/SKILL.md` | Discover retailer environment (locations, products, catalogues, inventory) and generate valid test entity creation payloads dynamically |
+| Settings management | `content/dev/skills/fluent-settings/SKILL.md` | Manage retailer settings — discover, audit against workflows, create/update, migrate between environments |
+| Retailer environment configuration | `content/dev/skills/fluent-retailer-config/SKILL.md` | Configure retailer environments — create locations, networks, catalogues, inventory, carriers via GraphQL |
+| Module inventory, classification, and structure validation | `content/dev/skills/fluent-module-validate/SKILL.md` | Inventory all deployed modules (reference vs custom), classify by symbolic name, validate custom extension structure; cached JSON artifacts |
+| OOTB-vs-custom rule decision | `content/dev/skills/fluent-rule-scaffold/SKILL.md` | Pre-scaffolding check: search registered rules via plugin.list, recommend OOTB if match exists, scaffold custom only when needed |
+| MCP extension tool reference (syntax/limits) | `content/mcp-extn/skills/fluent-mcp-tools/SKILL.md` | Canonical tool-level reference |
+| MCP core setup and GraphQL core utilities | `content/mcp-official/skills/fluent-mcp-core/SKILL.md` | Canonical official MCP server reference |
+| Account connection, workspace discovery, JAR decompilation, and cached state | `content/cli/skills/fluent-connect/SKILL.md` | Guided onboarding — discovers profiles, wires MCP, downloads workflows, decompiles JARs, builds rule inventory, persists workspace state |
+| Connection topology, cross-entity dependency maps, static-vs-dynamic runtime diffs, webhook/setting conformance | `content/dev/skills/fluent-connection-analysis/SKILL.md` | Topology analysis, orphan detection, process flow classification, --validate mode for runtime coverage comparison, settings conformance inventories |
+| JOB/BATCH entity lifecycle diagnostics and monitoring | `content/dev/skills/fluent-job-batch/SKILL.md` | JOB/BATCH orchestration lifecycle, batch ingestion monitoring, job status tracking |
+| Session change tracking and audit reporting (text + JSON) | `content/dev/skills/fluent-session-summary/SKILL.md` | Running change log of all write operations, skill invocations (with gate results and handoff signals), and MCP tool calls; structured summary on demand; lightweight JSON export |
+| Module skeleton scaffolding (Maven, POMs, module.json, rules) | `content/dev/skills/fluent-module-scaffold/SKILL.md` | New-vs-extend decision tree; generates buildable module under `accounts/<PROFILE>/SOURCE/` |
+| Scope document decomposition into task lists | `content/dev/skills/fluent-scope-decompose/SKILL.md` | Parses ADD scope docs into ordered tasks with dependency DAG, skill mappings, ambiguity flags |
+| Version lifecycle (read, bump, sync, tag) | `content/dev/skills/fluent-version-manage/SKILL.md` | Semver bumps across POM files, module.json, CHANGELOG; git tag creation |
+| Pre-deployment quality gates | `content/dev/skills/fluent-pre-deploy-check/SKILL.md` | 26 gates across 8 phases; blocks deployment on critical failures |
+| Machine-readable compliance audit export | `content/dev/skills/fluent-session-audit-export/SKILL.md` | JSON audit trail with `skillInvocations[]`, `toolCalls[]`, `decisionTrail[]`, traceability matrix, rollback commands, compliance metadata. Tracks gate results, handoff signals, and full decision chain. |
+| Feature reverse-engineering and architecture documentation | `content/dev/skills/fluent-feature-explain/SKILL.md` | Synthesizes workflow, code, connection, and runtime analysis into a persisted Feature Architecture Document with Mermaid diagrams. Tiered evidence: plugin.list (always) → decompiled JAR / original source → runtime. Auto-discovers entities for runtime, decompiles JARs when no source. Includes Analysis Confidence section with per-rule evidence levels. |
+| Feature implementation planning (multi-artifact) | `content/dev/skills/fluent-feature-plan/SKILL.md` | Produces comprehensive 18-section feature plans with universal NEW/EXISTING/MODIFIED/REUSED/OOTB Source classification across all artifacts (rules, rulesets, statuses, settings, webhooks, GraphQL ops, cross-entity impacts). For NEW rules: pseudo logic contract. For OOTB: prop configuration. Template at `PLAN_TEMPLATE.md` (sibling file in skill directory). |
+| Source code onboarding into Fluent module format | `content/dev/skills/fluent-source-onboard/SKILL.md` | Restructures non-standard Java source (loose files, decompiled JARs, Gradle projects, partial modules) into Maven multi-module Fluent extension module format. Validates with module-validate, attempts build, reconciles against deployed rules. |
+| Sourcing framework reference (profiles, strategies, conditions, criteria, scoring, extensions) | `content/dev/skills/fluent-sourcing/SKILL.md` | Comprehensive reference for Responsive Sourcing Framework v2.1+. Covers evaluation flow, 10 condition operators, 11 built-in criteria with scoring models, normalization algorithm, permutation search, settings schema, workflow integration rules, custom Java extensions, and operational GraphQL patterns. Chains to `/fluent-rule-scaffold` for custom extension wiring, `/fluent-workflow-builder` for sourcing rulesets, `/fluent-settings` for sourcing settings CRUD. |
+| Business requirements gathering (interactive wizard + document analysis) | `content/dev/skills/fluent-use-case-discover/SKILL.md` | Structured business spec production that feeds feature planning. Interactive mode walks through use cases, actors, business rules. Document analysis mode extracts from existing docs. |
+| Feature lifecycle dashboard and status tracking | `content/dev/skills/fluent-feature-status/SKILL.md` | Scans all `features/*/status.json`, presents consolidated table with filtering, sorting, and attention items across profiles |
+| Feature archival and lifecycle cleanup | `content/dev/skills/fluent-archive/SKILL.md` | Transitions features to ARCHIVED status with confirmation gate. Blocked for IN_PROGRESS without --force. |
+| Deployment rollback (workflows, modules, settings) | `content/dev/skills/fluent-rollback/SKILL.md` | Guided rollback with mandatory planning gate and dry-run mode. Workflow version revert, module redeploy, settings restore. |
+| Workspace structure visualization | `content/dev/skills/fluent-workspace-tree/SKILL.md` | Read-only annotated workspace tree showing all artifacts by category with counts and status overlays |
+| Implementation reverse-engineering and feature inventory | `content/dev/skills/fluent-implementation-map/SKILL.md` | Top-of-pyramid analysis: discovers features from workflows/rules/settings, maps cross-feature dependencies, scores customisation depth, identifies gaps. Output to `analysis/implementation-map/`. |
+| Workflow deployment with validation and fallback | `content/dev/skills/fluent-workflow-deploy/SKILL.md` | MCP-primary workflow upload with pre-flight checks, version verification, automatic REST API fallback, and rollback support |
+| Data module scaffolding (no Java plugins) | `content/dev/skills/fluent-data-module-scaffold/SKILL.md` | Generates module structure with assets directories, module.json, config template, and build script for non-plugin modules |
+| Mermaid diagram syntax validation | `content/dev/skills/fluent-mermaid-validate/SKILL.md` | Internal-only skill. Validates stateDiagram-v2, sequenceDiagram, flowchart, erDiagram syntax. Called by diagram-generating skills. |
+| Mystique manifest validation (schema, components, props, queries, i18n) | `content/dev/skills/fluent-mystique-validate/SKILL.md` | 49 validation rules across 6 phases. Canonical OOTB component alias registry (73 aliases). Schema compliance, component resolution, data/query validation, template string checking, prop verification, cross-manifest consistency. |
+| Mystique manifest building and editing | `content/dev/skills/fluent-mystique-builder/SKILL.md` | 6 operations (create manifest, add page, add component, build fragment, generate data query, edit manifest). 7 composition patterns. Entity type-to-GraphQL query mapping. Full manifest v2.0 schema. Build vs Configure decision framework. |
+| Mystique SDK component scaffolding | `content/dev/skills/fluent-mystique-scaffold/SKILL.md` | Generate complete buildable SDK component projects (webpack, TypeScript, Storybook, Jest, component registration). Only invoked when Build vs Configure framework determines OOTB components cannot meet the requirement. |
+| Mystique manifest analysis and complexity scoring | `content/dev/skills/fluent-mystique-analyze/SKILL.md` | 7 analysis dimensions with weighted complexity scoring (0-100). 15 pattern detection rules. Mermaid diagram generation (route graph, component tree, data flow). Architectural health assessment. |
+
+## Reconciliation Rules
+
+- Event API source docs are selectively extracted into skills; do not mirror full product docs.
+- If deployment logic changes, update `flow-run` and `fluent-module-deploy`; link from `fluent-build` rather than duplicating deploy instructions.
+- If workflow command syntax changes, update `fluent-workflow`; `fluent-workflow-builder` should reference it for operational steps.
+- If MCP tool contracts change, update `fluent-mcp-tools` first; other skills should reference it for request syntax and limits.
+- If workflow/ruleset intent is ambiguous, escalate to source/decompile flow owned by `fluent-trace` + `DEV_WORKFLOW.md` before making behavioral claims.
+- If module structure checks change, update `fluent-module-validate` first; `fluent-build` and `fluent-module-deploy` should read the cached report rather than duplicating checks.
+- Keep skill files focused on decision logic and patterns; keep low-level command/tool reference centralized.
+- If Mystique component registry or manifest schema changes, update `fluent-mystique-validate` first (canonical OOTB alias list); `fluent-mystique-builder` and `fluent-mystique-analyze` reference it for component resolution.
+- Frontend skills (`fluent-mystique-*`) own all Mystique/manifest/UI work. Backend skills should never generate or modify manifests. Cross-domain features route through `/fluent-feature-plan` at the orchestrator level.
+
+## Round-Robin Debugging Protocol
+
+| Entry intent | Route to | Avoid |
+|---|---|---|
+| "What actions are available at this status?" | `fluent-transition-api` | Re-implementing transition discovery in other skills |
+| "How do events/filters/causality work?" | `fluent-event-api` | Running full root-cause workflow here |
+| "How do I call this MCP tool?" | `fluent-mcp-tools` | Redefining tool contracts per skill |
+| "Run workflow end-to-end validation" | `fluent-e2e-test` | Duplicating trace decision trees |
+| "Why did this fail / entity stuck?" | `fluent-trace` | Repeating generic setup when failure context is already known |
+| "Explain feature / how does X work / document this flow" | `fluent-feature-explain` | Running individual analysis skills without synthesizing into a document |
+| "Plan this feature / implement curbside / design the return flow" | `fluent-feature-plan` | Using individual skills without a comprehensive plan first |
+| "How does sourcing work / configure sourcing profile / debug sourcing" | `fluent-sourcing` | Reimplementing sourcing logic reference in other skills |
+| "Gather requirements / create business spec / define use cases" | `fluent-use-case-discover` | Starting `/fluent-feature-plan` without an approved spec |
+| "Show feature status / what's in progress / feature dashboard" | `fluent-feature-status` | Manually scanning feature directories |
+| "Archive this feature / mark as done / close feature" | `fluent-archive` | Manually editing status.json |
+| "Roll back / undo deployment / revert workflow" | `fluent-rollback` | Manual GraphQL mutations or file restoration |
+| "Show workspace / what's where / directory structure" | `fluent-workspace-tree` | Running `ls` or `find` commands |
+| "Implementation map / what's been built / feature inventory / reverse engineer account" | `fluent-implementation-map` | Running individual analysis skills piecemeal |
+| "Deploy workflow / upload workflow JSON" | `fluent-workflow-deploy` | Using `fluent-workflow` for deployment (that's read-only operations) |
+| "Validate Mermaid / check diagram syntax" | `fluent-mermaid-validate` | Manual syntax checking |
+| "Bootstrap account / set up new environment / initialize workspace" | `fluent-bootstrap` | Manual multi-step setup |
+| "Create profile / switch profile / manage environments" | `fluent-profile` | Manual CLI profile management |
+| "Ready for launch / go-live readiness / production audit" | `fluent-rfl-assess` | Manual checklist-based assessment |
+| "Build manifest / create page / add route / edit UI" | `fluent-mystique-builder` | Building manifests outside the builder skill |
+| "Validate manifest / check UI / lint manifest" | `fluent-mystique-validate` | Re-implementing component validation elsewhere |
+| "Scaffold SDK component / new Mystique project" | `fluent-mystique-scaffold` | Building SDK projects without the Build vs Configure decision framework |
+| "Analyze manifest / UI audit / manifest complexity" | `fluent-mystique-analyze` | Re-implementing analysis elsewhere |
+
+Handoff rule: when E2E fails, pass `entityRef`, `entityType`, `eventId` (if available), and expected vs actual status to `fluent-trace`.