@fluentcommerce/ai-skills 0.1.0

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

@@ -0,0 +1,56 @@
+---
+name: fluent-rfl
+description: Fluent Commerce Ready For Launch (RFL) assessment agent. Analyzes workflows, custom rules, GraphQL usage, and architecture to determine production readiness. Triggers on "rfl assessment", "ready for launch", "production readiness", "go-live check".
+tools: Bash, Read, Write, Edit, Glob, Grep
+model: inherit
+skills: fluent-rfl-assess
+---
+
+# Fluent RFL Assessment Agent
+
+You are a Fluent Commerce Ready For Launch specialist. You perform comprehensive assessments of Fluent Commerce implementations to determine production readiness.
+
+## Assessment Areas
+
+### 1. Workflow Analysis
+- Naming conventions compliance
+- Duplicate ruleset detection
+- Orphaned ruleset identification
+- Cyclic dependency detection
+- State machine completeness
+
+### 2. Custom Rules Review
+- Java code quality and best practices
+- GraphQL usage patterns
+- Error handling coverage
+- Test coverage analysis
+- Performance considerations
+
+### 3. Configuration Audit
+- Settings completeness
+- User and role setup
+- Catalogue configuration
+- Network topology
+- Location setup
+
+### 4. Integration Health
+- Webhook configuration
+- Event processing patterns
+- External system connectivity
+- Error retry mechanisms
+
+## Assessment Output
+
+The RFL report includes:
+- Overall readiness score (0-100)
+- Risk assessment (Critical / High / Medium / Low)
+- Prioritized recommendations
+- Detailed findings per area
+- Go/No-Go recommendation
+
+## Key Behaviors
+
+1. **Be thorough** - Check all workflows, not just the primary ones
+2. **Verify, don't assume** - Query the live environment for actual state
+3. **Prioritize findings** - Critical blockers first, nice-to-haves last
+4. **Provide actionable recommendations** - Not just problems, but solutions

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

@@ -0,0 +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`.

package/docs/CAPABILITY_MAP.md

@@ -0,0 +1,77 @@
+# 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`.

package/docs/CLI_COVERAGE.md

@@ -0,0 +1,47 @@
+# Fluent CLI Coverage Matrix
+
+This matrix tracks how fully the `cli` skill group covers Fluent CLI command families.
+
+Use statuses:
+
+- `full` - dedicated skill with operational guidance and troubleshooting
+- `partial` - covered indirectly (for example via bootstrap flow) but not deep
+- `missing` - no owned skill yet
+
+## Coverage
+
+| Command Family | Status | Owner Skill | Notes |
+|---|---|---|---|
+| `fluent profile *` | `full` | `content/cli/skills/fluent-profile/SKILL.md` | Create/use/update/list/export profile lifecycle |
+| `fluent retailer *` | `full` | `content/cli/skills/fluent-cli-retailer/SKILL.md` | Create/list retailers and post-create context validation |
+| `fluent module *` | `full` | `content/cli/skills/fluent-module-deploy/SKILL.md` | Describe/config/install/list with deployment safeguards |
+| `fluent workflow *` | `full` | `content/cli/skills/fluent-workflow/SKILL.md` | List/download/merge and operational usage patterns |
+| `fluent workflowlog *` | `full` | `content/cli/skills/fluent-workflow/SKILL.md` | List/describe/insert/delete fragment history operations |
+| `fluent setting *` | `full` | `content/cli/skills/fluent-cli-settings/SKILL.md` | List/get settings with profile/retailer context checks |
+| Cross-family routing | `full` | `content/cli/skills/fluent-cli-index/SKILL.md` | Master router for broad/mixed Fluent CLI requests |
+| `fluent mcp server *` | `full` | `content/cli/skills/fluent-cli-mcp-cicd/SKILL.md` | CLI-group guidance plus handoff path to official MCP core skill |
+| Account bootstrap flow | `full` | `content/cli/skills/fluent-bootstrap/SKILL.md` | Profile + retailer + module bootstrap workflow |
+| CI/CD guarded deploy pattern | `full` | `content/cli/skills/fluent-cli-mcp-cicd/SKILL.md` | Pipeline-safe checks and explicit deploy confirmation pattern |
+
+## Guide Section Alignment
+
+This maps the major sections from `Fluent CLI Complete Guide` to skill coverage.
+
+| Guide Section | Status | Primary Owner |
+|---|---|---|
+| Quick Start | `full` | `fluent-bootstrap` + `fluent-cli-index` |
+| Profile Management | `full` | `fluent-profile` |
+| Retailer Management | `full` | `fluent-cli-retailer` |
+| Module Management | `full` | `fluent-module-deploy` |
+| Workflow Management | `full` | `fluent-workflow` |
+| Settings Management | `full` | `fluent-cli-settings` |
+| MCP Integration | `full` | `fluent-cli-mcp-cicd` (+ `fluent-mcp-core` for official tool details) |
+| Troubleshooting | `partial` | distributed across each skill's troubleshooting sections |
+| CI/CD Integration | `full` | `fluent-cli-mcp-cicd` + `flow-run` command docs |
+| Deep developer how-to examples | `partial` | `dev` group skills and `Fluent CLI` docs |
+
+## Routing Rule
+
+For broad requests (for example "handle Fluent CLI end-to-end"), start with `/fluent-cli-index`, then delegate to the command-family specialist.
+
+If the request needs official MCP server internals/tool semantics, hand off to `/fluent-mcp-core`.