# Agents and Skills Guide

> [!CAUTION]
> **EXPERIMENTAL - LABS PROJECT**
>
> This package is not production-ready. No stability guarantees, no support, no warranty. See `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 all 64 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 |
|---|---|
| `docs/index.md` | Docs hub and reading order |
| `README.md` | Install, package overview, top-level architecture |
| `docs/getting-started.md` | First-run walkthrough |
| `docs/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/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, modules, settings, events, tracing, Java, Maven, or deployment | Backend implementation and runtime operations | `/fluent-workflow-builder`, `/fluent-rule-scaffold`, `/fluent-module-scaffold`, `/fluent-build`, `/fluent-trace`, `/fluent-settings` |
| `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-analyze`, `/fluent-feature-status` |
| Requirements | Turn business need into an approved spec | `/fluent-use-case-discover` |
| Phasing | Split a large approved feature into vertical slices | `/fluent-feature-phase` |
| Technical planning | Produce the implementation contract for multi-artifact work | `/fluent-feature-plan` |
| Backend implementation | Change workflows, rules, modules, settings, or environment config | `/fluent-workflow-builder`, `/fluent-rule-scaffold`, `/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-validate`, `/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, monitor health, or roll back safely | `/fluent-trace`, `/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` |

## 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-settings` | Reads settings via the Fluent CLI | You want CLI-based setting inspection or auditing |
| `/fluent-cli-reference` | Provides exact Fluent CLI command and flag reference | You need command syntax, flags, or examples |
| `/fluent-cli-index` | Routes broad CLI questions to the right CLI skill | 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-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 and next actions | You want to know what is in progress, blocked, or ready next |
| `/fluent-feature-dashboard` | Generates or serves the live feature dashboard in HTML | You want a browser view of feature artifacts, reports, 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-feature-phase` | Breaks a large approved feature into independently deliverable vertical slices | The feature is too large for one plan-build-deploy cycle |
| `/fluent-feature-plan` | Produces the technical implementation contract across artifacts | The work spans multiple artifacts such as rules, workflows, settings, and UI |
| `/fluent-scope-decompose` | Converts a structured scope document into ordered tasks and dependencies | You already have a scope pack and need executable work items |
| `/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` | Analyzes status graphs, event chains, orphaned rulesets, and workflow quality | You want to understand or validate 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-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 | Source changes are ready to compile and package |
| `/fluent-version-manage` | Reads, bumps, syncs, and tags versions across files | You are preparing or aligning a release version |
| `/fluent-source-onboard` | 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-validate` | Validates manifest schema, components, queries, templates, and i18n | You need to verify a manifest before deployment |
| `/fluent-mystique-analyze` | Analyzes manifest complexity, usage patterns, and architectural health | 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-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-feedback` | Reviews skill outcomes and promotes confirmed learnings | You are tuning skill quality or reviewing recurring issues |

## 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` |
| "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` |
| "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.
