@fluentcommerce/ai-skills 0.13.0 → 0.14.0

package/docs/INDEX.md

@@ -0,0 +1,40 @@
+# Fluent AI Skills — Documentation
+
+> [!CAUTION]
+> **EXPERIMENTAL - LABS PROJECT**
+>
+> This package is not production-ready. No stability guarantees, no support, no warranty. See `../README.md` for the full disclaimer.
+
+## Reading Order
+
+Follow the numbered path. Most people only need docs 1 and 2.
+
+| # | Doc | Time | What you get |
+|---|-----|------|-------------|
+| **1** | [Your First Session](01-first-session.md) | 20 min | Installed, connected, first results — the minimum to be productive |
+| **2** | [Prompt Guide](02-prompt-guide.md) | 10 min | "I'm building X, what do I type?" — progressive skill navigator with prompt chains |
+| **3** | [Use Cases](03-use-cases.md) | Browse | 21 real scenarios walked through end-to-end with exact prompts and expected output |
+| **4** | [Onboarding Plan](04-onboarding-plan.md) | Reference | Structured 2-week team ramp (skip if solo) |
+
+**Hitting errors?** Jump to [Setup Reference & Troubleshooting](05-getting-started.md) — prerequisites, workspace layout, and fixes.
+
+**Need the full lifecycle protocol?** See [Development Workflow](06-dev-workflow.md) — lifecycle gates, deploy, promote, rollback.
+
+## Reference (look up when needed)
+
+| Topic | Doc |
+|-------|-----|
+| MCP server setup, auth, multi-profile switching | [mcp-servers.md](mcp-servers.md) |
+| Manifest write-safety rules | [manifest-safety.md](manifest-safety.md) |
+| Workflow upload methods and caching layers | [workflow-reference.md](workflow-reference.md) |
+| Browser automation for UI testing | [chrome-devtools-mcp-reference.md](chrome-devtools-mcp-reference.md) |
+
+## Deep Reference
+
+You don't need these to get started — they're for when you want the full picture.
+
+| Doc | What's in it |
+|-----|-------------|
+| [fluent-ai-skills-reference.md](fluent-ai-skills-reference.md) | Comprehensive single-doc reference — architecture, MCP tools (55+), workspace conventions, feature lifecycle. Overlaps with the docs above; use this when you prefer searching one file. |
+| [agents-and-skills-guide.md](agents-and-skills-guide.md) | Agent routing tables, all 60+ skills with invocation rules and SDLC mapping |
+| [capability-map.md](capability-map.md) | Which skill owns which capability — the ownership backstop for routing conflicts |

package/docs/agents-and-skills-guide.md

@@ -0,0 +1,199 @@
+# Agents and Skills Guide
+
+> [!CAUTION]
+> **EXPERIMENTAL - LABS PROJECT**
+>
+> This package is not production-ready. No stability guarantees, no support, no warranty. See [`../README.md`](../README.md) for the full disclaimer.
+
+This is the fastest way to understand the runtime model for `@fluentcommerce/ai-skills`:
+
+- which agent handles what
+- which skill to invoke
+- when to invoke it
+- where it fits in the SDLC
+
+This guide covers all 6 agents and 60+ skills currently registered in `metadata.json`.
+
+## How Invocation Works
+
+1. Start with natural language when you are outcome-focused.
+   Example: "Explain how Home Delivery works" or "Add a page to the OMS manifest".
+2. Use a slash command when you know the exact skill you want.
+   Example: `/fluent-feature-plan`, `/fluent-workflow-builder`, `/fluent-ui-test`.
+3. Treat agents as routers, not as commands.
+   Agents are selected automatically from intent. In normal use, you do not manually invoke `fluent-dev` or `fluent-backend-dev`.
+4. Use package CLI commands for installation and platform wiring, not feature delivery.
+   Example: `npx @fluentcommerce/ai-skills install`, `status`, `uninstall`, `mcp-setup`.
+
+## Practical Rules
+
+- Use natural language first if you are not sure which skill is correct.
+- Use slash commands when you want precise control.
+- Read-only skills are usually safe at any time: status, explain, analyze, validate, trace, review, reference.
+- Build, scaffold, deploy, rollback, and environment-changing skills usually sit behind planning or approval gates.
+- Slash commands are Claude Code friendly. Natural-language routing is the safer default across tools.
+
+## Best Companion Docs
+
+| Document | Best for |
+|---|---|
+| `INDEX.md` | Docs hub and reading order |
+| `../README.md` | Install, package overview, top-level architecture |
+| `docs/05-getting-started.md` | Setup reference and troubleshooting |
+| `docs/03-use-cases.md` | Example prompts and expected outcomes |
+| `docs/capability-map.md` | Capability ownership backstop and maintainer reference |
+| `docs/fluent-ai-skills-reference.md` | Deep operational reference |
+| `docs/06-dev-workflow.md` | End-to-end autonomous delivery loop |
+
+## Agent Catalog
+
+| Agent | Group | Auto-route when | What it owns | Good starting skills |
+|---|---|---|---|---|
+| `fluent-dev` | `dev` | The request spans frontend and backend, or you need planning, explain, mapping, status, or E2E coordination | Cross-cutting lifecycle orchestration | `/fluent-use-case-discover`, `/fluent-feature-plan`, `/fluent-feature-explain`, `/fluent-feature-status`, `/fluent-e2e-test` |
+| `fluent-backend-dev` | `dev` | The request mentions workflows, rules, rule tests, modules, settings, events, tracing, Java, Maven, or deployment | Backend implementation and runtime operations | `/fluent-workflow-builder`, `/fluent-rule-scaffold`, `/fluent-rule-test`, `/fluent-module-scaffold`, `/fluent-build`, `/fluent-trace`, `/fluent-entity-flow-diagnose` |
+| `fluent-frontend-dev` | `dev` | The request mentions manifests, pages, routes, components, Mystique, SDK projects, frontend build, or browser UI verification | Frontend implementation and UI verification | `/fluent-mystique-builder`, `/fluent-mystique-scaffold`, `/fluent-frontend-build`, `/fluent-ui-test`, `/fluent-frontend-review` |
+| `fluent-cli` | `cli` | The request is really about Fluent CLI commands, profiles, retailers, workflow download/listing, or module install operations | CLI family routing and command guidance | `/fluent-connect`, `/fluent-profile`, `/fluent-cli-retailer`, `/fluent-module-deploy`, `/fluent-workflow` |
+| `fluent-mcp` | `mcp-extn` | The request is about MCP servers (extension or official CLI), workflow download/list, GraphQL build/validate, events, batch, entities, metrics, or webhook validation | MCP tool usage, payload contracts, and core GraphQL/workflow utilities | `/fluent-mcp-tools`, `/fluent-mcp-core` |
+| `fluent-rfl` | `rfl` | The request is a production-readiness or go-live audit | Readiness assessment and risk reporting | `/fluent-rfl-assess` |
+
+## SDLC Cheat Sheet
+
+| Stage | Goal | Start here |
+|---|---|---|
+| Environment setup | Get the workspace, profile, retailer, and MCP wiring ready | `/fluent-bootstrap`, `/fluent-connect`, `/fluent-profile`, `/fluent-cli-mcp-cicd` |
+| Discover current state | Understand what already exists before changing anything | `/fluent-implementation-map`, `/fluent-feature-explain`, `/fluent-workflow-analyzer`, `/fluent-mystique-assess`, `/fluent-feature-status`, `/fluent-account-snapshot` |
+| Requirements | Turn business need into an approved spec | `/fluent-use-case-discover` |
+| Phasing | Split a large approved feature into vertical slices | `/fluent-scope-plan` |
+| Technical planning | Produce the implementation contract for multi-artifact work | `/fluent-feature-plan` |
+| Backend implementation | Change workflows, rules, rule tests, modules, settings, or environment config | `/fluent-workflow-builder`, `/fluent-rule-scaffold`, `/fluent-rule-test`, `/fluent-module-scaffold`, `/fluent-settings` |
+| Frontend implementation | Change manifests, SDK components, frontend build/test assets | `/fluent-mystique-builder`, `/fluent-mystique-scaffold`, `/fluent-mystique-component`, `/fluent-frontend-build` |
+| Validate and build | Run structural, code, and pre-deploy quality gates | `/fluent-module-validate`, `/fluent-mystique-assess`, `/fluent-frontend-review`, `/fluent-pre-deploy-check`, `/fluent-build` |
+| Deploy | Push module, workflow, or settings changes | `/fluent-module-deploy`, `/fluent-workflow-deploy`, `/fluent-settings` |
+| Test and verify | Confirm behavior in API, workflow, and browser layers | `/fluent-test-data`, `/fluent-e2e-test`, `/fluent-transition-api`, `/fluent-ui-test` |
+| Diagnose and recover | Trace failures, compare runtime vs workflow intent, monitor health, or roll back safely | `/fluent-trace`, `/fluent-entity-flow-diagnose`, `/fluent-system-monitoring`, `/fluent-connection-analysis`, `/fluent-rollback` |
+| Audit and wrap-up | Summarize, assess readiness, export audit trail, or archive | `/fluent-rfl-assess`, `/fluent-session`, `/fluent-archive`, `/fluent-skill-observability` |
+
+## Skills by Lifecycle
+
+### 1. Setup and Platform Access
+
+| Skill | What it does | Invoke when |
+|---|---|---|
+| `/fluent-bootstrap` | Creates a new Fluent account workspace end-to-end: profile, retailer, modules, and initial setup | You are starting from a brand-new account or environment |
+| `/fluent-connect` | Connects an existing account, wires MCP, downloads workflows, scans source, and prepares the workspace | You are starting work in an existing tenant or switching into a prepared workspace |
+| `/fluent-profile` | Manages Fluent CLI profiles | Credentials, account context, or active profile need to change |
+| `/fluent-cli-retailer` | Lists or creates retailers and validates retailer CLI context | Retailer admin or environment setup is the task |
+| `/fluent-cli-reference` | Provides exact Fluent CLI command and flag reference, and routes broad CLI questions | You need command syntax, flags, or examples, or the request mixes profiles, retailers, workflows, modules, and settings |
+| `/fluent-cli-mcp-cicd` | Sets up the CLI MCP server and CI/CD-safe automation patterns | You are wiring MCP or building deployment automation |
+| `/fluent-mcp-core` | Covers official CLI MCP setup plus GraphQL build, validate, execute, and workflow list/download | You want built-in MCP server workflows and GraphQL utilities (now under `mcp-extn` group) |
+| `/fluent-mcp-tools` | Documents the extension MCP tool contracts for events, GraphQL, entities, metrics, workflows, batch, and cache | You need exact MCP payload shape, limits, or tool selection |
+
+### 2. Discovery, Documentation, and Planning
+
+| Skill | What it does | Invoke when |
+|---|---|---|
+| `/fluent-account-snapshot` | Produces a lightweight account state inventory — retailers, workflows, modules, catalogues, settings, UI customizations | You want a quick overview of what exists in the account |
+| `/fluent-workspace-tree` | Shows an annotated workspace tree with artifact counts and status overlays | You need to orient yourself in the account workspace |
+| `/fluent-feature-status` | Shows the current feature lifecycle table, next actions, and generates the live feature dashboard | You want to know what is in progress, blocked, or ready next, or you want a browser view of feature artifacts and status |
+| `/fluent-implementation-map` | Reverse-engineers the account into a feature inventory and dependency map | You need a broad picture of what has been built |
+| `/fluent-feature-explain` | Produces an architecture-style explanation of an existing feature | The question is "how does this work?" rather than "change it" |
+| `/fluent-use-case-discover` | Turns vague requirements, notes, or a PRD into a structured business spec | You are starting a new feature and the business shape is not locked yet |
+| `/fluent-scope-plan` | Breaks features into phases and converts scope documents into ordered tasks and dependencies | The feature is too large for one plan-build-deploy cycle, or you have a scope pack and need executable work items |
+| `/fluent-feature-plan` | Produces the technical implementation contract across artifacts | The work spans multiple artifacts such as rules, workflows, settings, and UI |
+| `/fluent-goal` | Goal-oriented task tracking with deadlines and progress | You have a delivery target and want the AI to track progress toward it |
+| `/fluent-knowledge-init` | Captures account-specific conventions, business rules, integrations, and test context | You want reusable project knowledge in the workspace |
+| `/fluent-archive` | Archives a completed or abandoned feature and performs lifecycle cleanup | The feature is done and should be formally closed out |
+
+### 3. Backend Delivery
+
+| Skill | What it does | Invoke when |
+|---|---|---|
+| `/fluent-workflow` | Handles operational workflow CLI tasks such as list, download, merge, and workflow logs | You need workflow files or workflow CLI operations rather than design logic |
+| `/fluent-workflow-builder` | Creates or edits workflow JSON definitions, rulesets, statuses, and triggers | You are implementing or changing workflow behavior |
+| `/fluent-workflow-analyzer` | Validates and analyzes workflow JSON — status graphs, event chains, orphaned rulesets, trigger coverage, and structural correctness | You want to understand, validate, or audit a workflow before or after change |
+| `/fluent-workflow-deploy` | Deploys standalone workflow JSON with strict preflight and fallback paths | You need to ship workflow-only changes safely |
+| `/fluent-rule-scaffold` | Generates a new Java rule and test and wires it into the module manifest | New custom backend rule logic is required |
+| `/fluent-rule-test` | Generates or repairs backend rule tests using the repo's local harness conventions | A rule already exists and you need to add, fix, or backfill its tests |
+| `/fluent-rule-lookup` | Finds rules by name, annotation, or behavior across deployed modules and source code | You need to locate a rule, check what rules use a particular annotation, or audit rule coverage |
+| `/fluent-module-scaffold` | Creates a new Java/Maven Fluent extension module | You need a new plugin module rather than adding to an existing one |
+| `/fluent-data-module-scaffold` | Creates a data-only module with assets and build scripts but no Java plugins | You need a module for workflows, settings, or data assets only |
+| `/fluent-module-validate` | Validates module structure, contents, and classification | You want to check a module before build or deploy, or audit what exists |
+| `/fluent-build` | Builds and packages Fluent extension modules; also handles version reads, bumps, and sync | Source changes are ready to compile and package, or you need to prepare or align a release version |
+| `/fluent-module-convert` | Restructures non-standard or decompiled code into Fluent module format | You have code that does not yet match Fluent module conventions |
+| `/fluent-settings` | Discovers, audits, creates, updates, and migrates settings | Behavior depends on settings or settings need to be deployed |
+| `/fluent-retailer-config` | Creates and configures environment entities such as locations, networks, carriers, and catalogues | You are doing retailer environment setup or cloning |
+| `/fluent-inventory-catalog` | Manages virtual inventory catalogues, positions, segments, and control groups | The work is specifically about virtual inventory structures |
+| `/fluent-sourcing` | Provides the Responsive Sourcing Framework reference and operational patterns | You are designing or debugging sourcing and fulfilment allocation logic |
+| `/fluent-custom-code` | Analyzes existing custom backend code and produces reusable artifacts | You need to understand source-level behavior before changing it |
+| `/fluent-module-deploy` | Installs module ZIPs into target retailers | You are ready to deploy modules, bundled settings, or bundled workflow changes |
+
+### 4. Frontend Delivery
+
+| Skill | What it does | Invoke when |
+|---|---|---|
+| `/fluent-mystique-sdk-reference` | Serves as the SDK and registry reference for Mystique component development | You need exact hook, registry, or SDK usage patterns before coding |
+| `/fluent-mystique-builder` | Creates or edits Mystique manifests, routes, pages, and components | The UI change can be solved with manifest configuration |
+| `/fluent-mystique-assess` | Validates and analyzes manifest schema, components, queries, complexity, usage patterns, and architectural health | You need to verify a manifest before deployment, or you are auditing or reverse-engineering an existing frontend |
+| `/fluent-mystique-diff` | Compares customized manifests against deployed or baseline state | You need to know what changed or what is overridden |
+| `/fluent-mystique-preview` | Previews likely UI changes before a real deployment | You want fast visual iteration on layout or structure |
+| `/fluent-mystique-scaffold` | Scaffolds a brand-new Mystique SDK project | Configuration is not enough and a custom bundle is needed |
+| `/fluent-mystique-component` | Adds a component, field, or template helper to an existing SDK project | You already have a bundle and want to extend it |
+| `/fluent-frontend-build` | Runs local dev mode or full production frontend build gates | You need hot reload locally or a deployable SDK bundle |
+| `/fluent-frontend-review` | Performs a read-only audit of SDK code quality, GraphQL, docs, and readiness | You want a release-quality frontend review before shipping |
+| `/fluent-frontend-readme` | Generates or refreshes project README documentation from source | You need handover-quality docs for an SDK project |
+| `/fluent-ui-test` | Verifies deployed UI behavior in OMS or Store via browser automation | You need to prove the UI renders and behaves correctly in the real app |
+| `/fluent-ui-record` | Captures annotated walkthroughs and before/after evidence | You need screenshots, walkthrough evidence, or reporting artifacts |
+
+### 5. Test, Diagnose, and Operate
+
+| Skill | What it does | Invoke when |
+|---|---|---|
+| `/fluent-test-data` | Discovers live references and creates valid test entities dynamically | Tests need real environment-compatible data without hardcoding |
+| `/fluent-e2e-test` | Runs end-to-end scenarios and asserts state transitions | You want post-deploy functional verification across the workflow lifecycle |
+| `/fluent-transition-api` | Discovers available user actions at a given status | You are validating UI buttons, action visibility, or dynamic user action paths |
+| `/fluent-event-api` | Explains the event model, statuses, filters, and event contracts | The question is about event semantics or event query strategy |
+| `/fluent-trace` | Traces failed processing and surfaces runtime root cause | An entity is stuck, an event failed, or the runtime story is unclear |
+| `/fluent-entity-flow-diagnose` | Reconstructs the entity event chain and compares runtime against workflow intent | You have a real entity ref and want the complete expected-vs-observed diagnosis |
+| `/fluent-system-monitoring` | Monitors metrics, failure rates, latency, and event health | You are doing observability, triage, or health monitoring |
+| `/fluent-connection-analysis` | Maps cross-entity and cross-workflow topology and conformance | Dependencies, setting linkage, or runtime-vs-static drift need analysis |
+| `/fluent-job-batch` | Monitors and explains JOB and BATCH entity lifecycles | The work centers on batch ingestion or async job processing |
+| `/fluent-pre-deploy-check` | Runs pre-deployment quality gates across module, workflow, environment, and settings | You need a final go or no-go decision before deployment |
+| `/fluent-rollback` | Performs guided rollback for workflows, modules, or settings | A deployment must be reversed safely |
+| `/fluent-rfl-assess` | Audits production readiness for go-live | You need a launch-readiness or release-readiness review |
+
+### 6. Session, Audit, and Quality Loop
+
+| Skill | What it does | Invoke when |
+|---|---|---|
+| `/fluent-session` | Summarizes what changed in the current session in human-readable form; use `/fluent-session export` for a machine-readable JSON audit trail | You want a wrap-up, handover, decision chain summary, or structured audit export for CI/CD and compliance |
+| `/fluent-skill-observability` | Traces skill routing, generates routing reports, and captures feedback on skill performance | You want to understand which skill handled a request, review routing decisions, or tune skill quality |
+
+## Picking the Right Entry Point
+
+| If the user says... | Start with |
+|---|---|
+| "Help me set this workspace up" | `/fluent-connect` |
+| "We have an idea but need requirements" | `/fluent-use-case-discover` |
+| "Plan this feature" | `/fluent-feature-plan` |
+| "Explain what already exists" | `/fluent-feature-explain` or `/fluent-implementation-map` |
+| "Change workflow behavior" | `/fluent-workflow-builder` |
+| "Add a custom rule" | `/fluent-rule-scaffold` |
+| "Write or fix a rule test" | `/fluent-rule-test` |
+| "Create a module" | `/fluent-module-scaffold` or `/fluent-data-module-scaffold` |
+| "Build or deploy this backend change" | `/fluent-build`, then `/fluent-module-deploy` or `/fluent-workflow-deploy` |
+| "Change the UI" | `/fluent-mystique-builder` or `/fluent-mystique-scaffold` |
+| "Test in browser" | `/fluent-ui-test` |
+| "Why did this fail?" | `/fluent-trace` |
+| "Show me what happened vs what should have happened for this entity" | `/fluent-entity-flow-diagnose` |
+| "Is this safe to ship?" | `/fluent-pre-deploy-check` or `/fluent-rfl-assess` |
+
+## Maintenance Note
+
+If the agent or skill inventory changes, update this guide together with:
+
+- `metadata.json`
+- `README.md`
+- `docs/capability-map.md`
+- `docs/fluent-ai-skills-reference.md`
+
+This keeps the consolidated routing guide aligned with the package registry and the deeper reference docs.

package/docs/capability-map.md

@@ -0,0 +1,165 @@
+# Capability Ownership Map
+
+> [!CAUTION]
+> **🧪 EXPERIMENTAL — LABS PROJECT**
+> This package is not production-ready. No stability guarantees, no support, no warranty. See [README](../README.md) for full disclaimer.
+
+This document defines which command/skill is the source of truth for each capability.
+
+Use it to avoid duplicate guidance and conflicting instructions.
+
+If you want the higher-level "which agent/skill should I use, how do I invoke it, and where does it fit in the SDLC?" view, start with [Agents & Skills Guide](agents-and-skills-guide.md) and use this document as the ownership backstop.
+
+## 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 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 |
+| Complete CLI command reference and cross-family routing | `content/cli/skills/fluent-cli-reference/SKILL.md` | Canonical reference for every Fluent CLI command, flag, and option. Absorbs former `fluent-cli-index` (v0.12.0). |
+| 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 |
+| Entity-ref-first runtime-to-workflow diagnosis and expected-vs-observed diff | `content/dev/skills/fluent-entity-flow-diagnose/SKILL.md` | Single entry point for real-entity diagnosis that stitches runtime chain reconstruction to static workflow comparison |
+| 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/06-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 validation, analysis, and dependency mapping | `content/dev/skills/fluent-workflow-analyzer/SKILL.md` | Status graph, event chain tracing, orphan detection, JSON validation, trigger coverage, user action consistency. Absorbs former `fluent-workflow-validate` (v0.12.0). |
+| 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 |
+| Rule unit test generation and repair | `content/dev/skills/fluent-rule-test/SKILL.md` | Generate or repair JUnit 5 tests for Rubix rules. Classifies rule, matches local harness (RuleExecutor/TestExecutor/Mockito/WorkflowExecutor), applies patterns from `knowledge/platform/rule-test-patterns.md` |
+| 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-extn/skills/fluent-mcp-core/SKILL.md` | Canonical official MCP server reference (now under `mcp-extn` group) |
+| 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, audit reporting (text + JSON), and compliance export | `content/dev/skills/fluent-session/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; machine-readable JSON audit trail with `skillInvocations[]`, `toolCalls[]`, `decisionTrail[]`, traceability matrix, rollback commands, compliance metadata |
+| 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 and feature phasing | `content/dev/skills/fluent-scope-plan/SKILL.md` | Consolidated from `fluent-scope-decompose` + `fluent-feature-phase` (v0.12.0); parses scope docs into ordered tasks with dependency DAG, skill mappings, vertical slice delivery phases |
+| Pre-deployment quality gates | `content/dev/skills/fluent-pre-deploy-check/SKILL.md` | 35+ gates across 9 phases; blocks deployment on critical failures |
+| 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-module-convert/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. |
+| Account state inventory (lightweight snapshot) | `content/dev/skills/fluent-account-snapshot/SKILL.md` | MCP-first data collection of retailers, workflows, modules, catalogues, settings, and UI customizations with LLM summary |
+| 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 | `knowledge/mermaid-syntax-rules.md` | Internalized as knowledge doc. Validates stateDiagram-v2, sequenceDiagram, flowchart, erDiagram syntax. Referenced by diagram-generating skills. |
+| Mystique manifest validation and analysis | `content/dev/skills/fluent-mystique-assess/SKILL.md` | Consolidated from `fluent-mystique-validate` + `fluent-mystique-analyze` (v0.12.0); validation rules, OOTB component alias registry, complexity scoring, pattern detection, Mermaid diagrams, architectural health |
+| 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. |
+| Frontend SDK build pipeline (7 gates) | `content/dev/skills/fluent-frontend-build/SKILL.md` | TypeScript compilation → lint → tests with coverage → production webpack build → bundle verification (size, version.json) → externals check (React/MUI not bundled) → GraphQL schema validation (3-tier: source queries, deployed manifests, workflow cross-ref). Produces structured build report. |
+| Frontend SDK code quality audit (9 phases) | `content/dev/skills/fluent-frontend-review/SKILL.md` | TypeScript quality, React patterns, SDK compliance, GraphQL schema validation (3-tier), code documentation, test quality, README completeness, bundle health, deployment readiness. Graded A-F scoring. Read-only — does not auto-fix. |
+| Frontend SDK README generation | `content/dev/skills/fluent-frontend-readme/SKILL.md` | Auto-generates README.md from source code. Inspects ComponentRegistry registrations, hook usage, settings dependencies, GraphQL queries, and build config to produce accurate documentation. |
+| Mystique manifest CDN baseline diffing | `content/dev/skills/fluent-mystique-diff/SKILL.md` | Compare manifest settings against CDN baselines; shows customized vs default fragments, structural diffs, OOTB vs custom component classification |
+| Browser-based UI testing for deployed Mystique manifests | `content/dev/skills/fluent-ui-test/SKILL.md` | Chrome DevTools MCP-based browser testing — login, navigation, component rendering verification, screenshot capture, DOM snapshot, console error detection. Requires `chrome-devtools` server in `.mcp.json`. |
+| Skill system observability (trace, routing, feedback, quality) | `content/dev/skills/fluent-skill-observability/SKILL.md` | Consolidated from `fluent-feedback` + `fluent-skill-trace` + `fluent-skill-routing-report` (v0.12.0); unified trace, routing analysis, feedback dashboard, and quality audit |
+| Goal-directed autonomous orchestration | `content/dev/skills/fluent-goal/SKILL.md` | Takes any Fluent Commerce goal, decomposes into sub-goals, delegates to existing skills, verifies via MCP, self-critiques, and persists until done. Three autonomy levels, mandatory planning gate, critique protocol, failure pattern map |
+| Annotated UI walkthroughs and evidence recording | `content/dev/skills/fluent-ui-record/SKILL.md` | Captures before/after screenshots with DOM annotations, optional Chrome DevTools MCP video recording, manifest diff reports, and HTML evidence reports. Companion to `/fluent-ui-test`. |
+| Project knowledge initialization and management | `content/dev/skills/fluent-knowledge-init/SKILL.md` | Interactive wizard to set up partner conventions, client business rules, integrations, and test data in `accounts/<PROFILE>/knowledge/` directory. Supports doc ingestion, conversational capture, and progressive learning. |
+| Mystique Component SDK API reference lookup | `content/dev/skills/fluent-mystique-sdk-reference/SKILL.md` | Read-only reference for React hooks, composition primitives, field patterns, and Material-UI constraints for custom Fluent Commerce UI components |
+| OOTB rule reference lookup | `content/dev/skills/fluent-rule-lookup/SKILL.md` | Search and discover out-of-the-box Fluent Commerce reference module rules by keyword, entity type, module, or capability via MCP plugin_list |
+| Mystique SDK component addition | `content/dev/skills/fluent-mystique-component/SKILL.md` | Adds 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. |
+| Mystique UI preview (mock/modify/remove) | `content/dev/skills/fluent-mystique-preview/SKILL.md` | 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). |
+| Virtual inventory catalog management | `content/dev/skills/fluent-inventory-catalog/SKILL.md` | Manage Fluent Commerce virtual inventory: catalogues, positions, segments, feeds, and control groups. Schema-gated — only runs when VirtualSegment type exists. |
+
+## 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-assess` first (canonical OOTB alias list); `fluent-mystique-builder` references it for component resolution.
+- Frontend skills (`fluent-mystique-*`, `fluent-frontend-*`, `fluent-ui-test`) own all Mystique/manifest/UI/SDK work. Backend skills should never generate or modify manifests. Cross-domain features route through `/fluent-feature-plan` at the orchestrator level.
+- Browser-based UI testing (`fluent-ui-test`) requires Chrome DevTools MCP. If Chrome DevTools MCP is not configured, redirect user to add the `chrome-devtools` server entry to `.mcp.json`.
+
+## 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 |
+| "Compare runtime vs workflow for this entity ref" | `fluent-entity-flow-diagnose` | Manually chaining trace, workflow fetch, and topology diff |
+| "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 |
+| "Write tests for a rule / generate rule tests / fix rule test" | `fluent-rule-test` | Re-implementing test generation in other skills |
+| "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 |
+| "What's deployed / account snapshot / environment summary" | `fluent-account-snapshot` | Running individual queries piecemeal |
+| "Validate workflow / check workflow / lint workflow" | `fluent-workflow-analyzer` | Re-implementing validation in other skills |
+| "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" | `knowledge/mermaid-syntax-rules.md` | Reference knowledge doc directly |
+| "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-assess` | Re-implementing component validation elsewhere |
+| "Scaffold SDK component / new Mystique project" | `fluent-mystique-scaffold` | Building SDK projects without the Build vs Configure decision framework |
+| "Build SDK project / compile / run tests / check bundle" | `fluent-frontend-build` | Re-implementing build pipeline in other skills |
+| "Review frontend code / audit quality / check patterns" | `fluent-frontend-review` | Re-implementing code analysis in other skills |
+| "Generate README / document components" | `fluent-frontend-readme` | Manually writing README for SDK projects |
+| "Analyze manifest / UI audit / manifest complexity" | `fluent-mystique-assess` | Re-implementing analysis elsewhere |
+| "Test the page in browser / verify UI / check if page loads" | `fluent-ui-test` | Manual browser testing or re-implementing Chrome DevTools MCP logic in other skills |
+| "Show feedback / skill success rate / recurring issues" | `fluent-skill-observability` | Manually reading feedback JSONL files |
+| "Record UI walkthrough / capture before-after / evidence report" | `fluent-ui-record` | Manual screenshot gathering without annotations |
+| "Set up knowledge / import conventions / capture business rules" | `fluent-knowledge-init` | Manually writing knowledge files |
+| "Phase this feature / break into slices / delivery phases" | `fluent-scope-plan` | Manual phase planning |
+| "Show feature dashboard / open dashboard" | `fluent-feature-status` | Manually scanning feature directories |
+| "Add component to SDK project / new field / new helper" | `fluent-mystique-component` | Manually creating component files |
+| "Preview UI change / mock component / what will it look like" | `fluent-mystique-preview` | Manual manifest editing for preview |
+| "Manage inventory / virtual catalogue / segments" | `fluent-inventory-catalog` | Manual GraphQL inventory operations |
+| "Diff manifest / CDN vs custom / what's customized" | `fluent-mystique-diff` | Manual comparison of manifest fragments |
+| "SDK hook / hook API / SDK reference / useSettings" | `fluent-mystique-sdk-reference` | Searching SDK source code manually |
+| "Find rule / OOTB rule / what rule does X / rule catalog" | `fluent-rule-lookup` | Manual plugin_list queries |
+| "Skill trace / routing report / skill quality / audit skills" | `fluent-skill-observability` | Manually reading trace/feedback JSONL files |
+| "Decompose scope / task breakdown / scope to tasks" | `fluent-scope-plan` | Manual scope document parsing |
+
+Handoff rule: when E2E fails, pass `entityRef`, `entityType`, `eventId` (if available), and expected vs actual status to `fluent-trace`.
+
+## CLI Coverage Matrix
+
+Tracks how fully the `cli` skill group covers Fluent CLI command families.
+
+| Command Family | Status | Owner Skill |
+|---|---|---|
+| `fluent profile *` | full | `fluent-profile` |
+| `fluent retailer *` | full | `fluent-cli-retailer` |
+| `fluent module *` | full | `fluent-module-deploy` |
+| `fluent workflow *` | full | `fluent-workflow` |
+| `fluent workflowlog *` | full | `fluent-workflow` |
+| `fluent setting *` | full | `fluent-settings` |
+| Cross-family routing | full | `fluent-cli-reference` |
+| `fluent mcp server *` | full | `fluent-cli-mcp-cicd` |
+| Account bootstrap flow | full | `fluent-bootstrap` |
+| CI/CD guarded deploy | full | `fluent-cli-mcp-cicd` |
+
+Routing rule: for broad CLI requests, start with `/fluent-cli-reference`, then delegate to the command-family specialist. For official MCP server internals, hand off to `/fluent-mcp-core`.