# @fluentcommerce/ai-skills

[![npm](https://img.shields.io/npm/v/@fluentcommerce/ai-skills)](https://www.npmjs.com/package/@fluentcommerce/ai-skills) [![mcp-extn](https://img.shields.io/npm/v/@fluentcommerce/fluent-mcp-extn?label=mcp-extn)](https://www.npmjs.com/package/@fluentcommerce/fluent-mcp-extn)

> [!CAUTION]
> **🧪 EXPERIMENTAL — LABS PROJECT**
>
> This package is **NOT production-ready**. It is an internal labs experiment under active development.
>
> - **No stability guarantees** — skills, CLI options, MCP tool contracts, and config may change or break between any release
> - **No support** — this is not an officially supported Fluent Commerce product
> - **No warranty** — provided as-is for experimentation and internal evaluation only
> - **Do NOT use in production** without thorough review and explicit sign-off from your team
>
> Pin to an exact version (`@0.6.7`) if you depend on current behavior.

Teach your AI assistant to work with [Fluent Commerce](https://fluentcommerce.com) (distributed order management) — analyze workflows, scaffold rules, debug events, build manifests, and deploy — all through natural language.

**64 skills** · 6 agents · Claude Code

---

## Quick Start (copy-paste)

```bash
# 1. Install prerequisites (skip if already installed)
# Fluent CLI: https://docs.fluentcommerce.com/building-blocks/fluent-cli-package
npm install -g @anthropic-ai/claude-code

# 2. Create a Fluent CLI profile (get values from your Fluent account team)
fluent profile create MY_PROFILE \
  --id my-account-id \
  --username admin@example.com \
  --password "your-password" \
  --client-secret "your-client-secret" \
  --base-url "https://my-account-id.sandbox.api.fluentcommerce.com"

# 3. Create workspace, install skills + MCP
mkdir my-workspace && cd my-workspace
npx @fluentcommerce/ai-skills install --profile MY_PROFILE --profile-retailer "My Retailer"

# 4. Verify everything is set up correctly
npx @fluentcommerce/ai-skills doctor

# 5. Launch Claude Code (MUST be in the workspace folder)
claude
```

Then type this as your **first prompt** in Claude Code:

```
/fluent-connect --profile MY_PROFILE --retailer "My Retailer"
```

This downloads workflows, scans your account, and sets up the workspace. After that, just talk naturally:

```
"What's deployed on this account?"
"Help me build a return order workflow"
"Why is order HD-001 stuck?"
```

> **Common mistake:** If skills don't work, run `npx @fluentcommerce/ai-skills doctor` in the workspace folder. It checks every prerequisite and tells you exactly what to fix.

---

## How It Works

Claude Code is general-purpose — it doesn't know Fluent Commerce. This package injects Fluent-specific domain knowledge so Claude understands workflows, events, rules, GraphQL patterns, CLI commands, and deployment procedures.

```
  You ──► Claude Code
              │
              │  skills inject domain knowledge
              ▼
          AI Agent
           ╱    ╲
          ▼      ▼
   Fluent Commerce    Fluent UX Apps
     Platform           OMS / Store
   (fluent-mcp +      (chrome-devtools
    fluent-mcp-extn    browser automation)
    live API access)
```

The AI doesn't just know what to say — it calls live APIs via [MCP](https://modelcontextprotocol.io) (Model Context Protocol — the standard for connecting AI assistants to external tools) to query your workflows, fire events, check metrics, inspect manifests, and verify deployments in real time.

---

## Who Is This For?

<table>
<tr>
<td width="80" align="center"><h3>🔨</h3><b>Builder</b></td>
<td>
<b>Implementation consultants &amp; developers</b> building Fluent Commerce for clients. You touch workflows, rules, manifests, and deployments daily.
<br/><br/>
<b>Try these:</b><br/>
<code>"Help me define use cases for return orders"</code> → interactive wizard producing spec.md<br/>
<code>"Plan the return order feature"</code> → 18-section plan with diagrams, waits for approval<br/>
<code>"Build an ORDER::RETURN workflow"</code> → scaffolds rules, builds JSON, compiles, deploys<br/>
<code>"Add an appeasement form to the order page"</code> → builds manifest fragment, validates, deploys<br/>
<code>"Deploy ORDER::HD to staging"</code> → 26 pre-flight gates, deploy, verify
<br/><br/>
<b>Your skills:</b> The full lifecycle — <code>use-case-discover</code> → <code>feature-phase</code> (complex) → <code>feature-plan</code> → <code>rule-scaffold</code> → <code>workflow-builder</code> → <code>mystique-builder</code> → <code>module-deploy</code> → <code>e2e-test</code>
</td>
</tr>
<tr>
<td width="80" align="center"><h3>🔍</h3><b>Investigator</b></td>
<td>
<b>Support engineers &amp; debuggers</b> troubleshooting production issues — stuck orders, failed events, missing buttons, broken workflows.
<br/><br/>
<b>Try these:</b><br/>
<code>"Why is order HD-12345 stuck in BOOKED?"</code> → traces event history, finds root cause + fix<br/>
<code>"Show event failure rates for the last hour"</code> → metrics anomaly detection with alerts<br/>
<code>"The approve button is missing on credit memos"</code> → checks Transition API, modules, subtype<br/>
<code>"Trace event ON_SEND_FULFILMENT for this order"</code> → rule-by-rule execution breakdown
<br/><br/>
<b>Your skills:</b> <code>trace</code>, <code>transition-api</code>, <code>workflow-analyzer</code>, <code>system-monitoring</code>, MCP event &amp; metrics tools
</td>
</tr>
<tr>
<td width="80" align="center"><h3>📋</h3><b>Reviewer</b></td>
<td>
<b>Tech leads &amp; architects</b> assessing quality, auditing implementations, and running go-live readiness checks.
<br/><br/>
<b>Try these:</b><br/>
<code>"Run a Ready For Launch assessment"</code> → scored audit across workflows, rules, settings<br/>
<code>"Map the entire implementation"</code> → feature inventory with dependency graphs<br/>
<code>"Explain how Home Delivery works end-to-end"</code> → state diagrams, rules table, architecture.md<br/>
<code>"Analyze workflow connection topology"</code> → cross-entity dependency maps
<br/><br/>
<b>Your skills:</b> <code>rfl-assess</code>, <code>implementation-map</code>, <code>feature-explain</code>, <code>connection-analysis</code>, <code>custom-code</code>
</td>
</tr>
<tr>
<td width="80" align="center"><h3>🚀</h3><b>New Starter</b></td>
<td>
<b>Just joined the project.</b> Need to understand what's deployed before you can contribute. Don't know where anything is yet.
<br/><br/>
<b>Try these:</b><br/>
<code>"Set up my workspace"</code> → connects account, downloads workflows, scans code<br/>
<code>"What's deployed on this account?"</code> → full implementation inventory<br/>
<code>"Explain the custom rules"</code> → annotated analysis of all plugin code<br/>
<code>"Show me the feature dashboard"</code> → live status of all features in progress
<br/><br/>
<b>Your path:</b> <code>/fluent-connect</code> → <code>implementation-map</code> → <code>feature-explain</code> → <code>custom-code</code> → start building
</td>
</tr>
</table>

> **Don't see yourself?** These personas overlap. A builder debugs. A reviewer onboards. An investigator ships hotfixes. Start with whatever matches your current task — the AI routes to the right skills automatically.

---

## What Can You Do?

The [persona examples above](#who-is-this-for) show common prompts for each role. Here are additional capabilities:

| What you say | What happens |
|---|---|
| "Preview what the appeasement card looks like" | Three modes (ADD/MODIFY/REMOVE) with color-coded glow highlights, iterative refinement, before/after GIF generation |
| "Verify the OMS orders page works" | Browser login, navigate, DOM snapshot, screenshot evidence report |
| "Show event failure rates for the last hour" | Metrics anomaly detection with threshold alerts |
| "Trace event ON_SEND_FULFILMENT for this order" | Rule-by-rule execution breakdown with timing and error details |
| "Add an appeasement form to the order page" | Builds Mystique manifest fragment, validates against 86 components, deploys to OMS app |
| "What features are in progress?" | Reads `status.json` across all features, shows lifecycle state, resumes where you left off |

See all 27 scenarios with exact prompts: [docs/use-cases.md](docs/use-cases.md)

---

## Getting Started

**You don't need to clone a repository.** This is an npm package — you run it with `npx` in any empty folder and it sets up everything.

### Prerequisites

| Requirement | How to install | Verify |
|---|---|---|
| **Node.js 20+** | [nodejs.org](https://nodejs.org) | `node --version` |
| **Fluent CLI 2.0+** | [Install guide](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package) | `fluent --version` |
| **Claude Code** | `npm install -g @anthropic-ai/claude-code` | `claude --version` |
| **A Fluent Commerce account** | Contact your Fluent account team | You'll need the 5 values below |

> **Default target: Claude Code.** This package installs Claude plugins, Claude skills, and Claude slash-command workflows by default. It also has an **experimental Codex skills-only target** via `--target codex`, which copies skills into Codex’s `~/.codex/skills` runtime path and mirrors them to `~/.agents/skills` for compatibility. The generated workspace `.mcp.json` remains standard MCP configuration.

**Before you start, gather these 5 values from your Fluent account team:**

| Value | Example | Where it's used |
|---|---|---|
| Account ID | `my-account-id` | Profile creation (`--id`) |
| API Base URL | `https://my-account-id.sandbox.api.fluentcommerce.com` | Profile creation (`--base-url`) |
| Username | `admin@example.com` | Profile creation (`--username`) |
| Password | `your-password` | Profile creation (`--password`) |
| Client Secret | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` | Profile creation (`--client-secret`) — required for API auth |

> **Windows users:** All commands in this guide use Unix shell syntax (works in Git Bash, WSL, and PowerShell). For PowerShell, replace `\` line continuations with `` ` `` and `export VAR=val` with `$env:VAR="val"`. Paths like `~/.fluentcommerce/` map to `C:\Users\<you>\.fluentcommerce\` on Windows.

---

### Step 1 — Create a Fluent CLI profile

A **profile** is a named connection to your Fluent account stored securely in `~/.fluentcommerce/`.

```bash
fluent profile create MY_PROFILE \
  --id my-account-id \
  --username admin@example.com \
  --password "your-password" \
  --client-secret "your-client-secret" \
  --base-url "https://my-account-id.sandbox.api.fluentcommerce.com"
```

> Your Fluent account team provides the account ID, API base URL, and credentials. The `--client-secret` is required for API authentication.

Verify the profile and find your retailer ref:

```bash
fluent profile retailers MY_PROFILE
# Output example:
#   ACME Retail        (id: 2)
#   My Retailer        (id: 5)
# Copy the exact retailer name string — you'll use it in Step 2.
```

---

### Step 2 — Create a workspace and install skills

A **workspace** is just an empty directory where all your Fluent development work lives. You can name it anything:

```bash
mkdir my-fluent-workspace && cd my-fluent-workspace
git init    # recommended — tracks your work and enables .gitignore

# Replace MY_PROFILE with your profile name from Step 1
# Replace "My Retailer" with the EXACT retailer name from `fluent profile retailers` output
npx @fluentcommerce/ai-skills install --profile MY_PROFILE --profile-retailer "My Retailer"
```

This single command:
1. Installs the current Fluent skill catalog into Claude Code (marketplace plugin, or file-copy fallback)
2. Creates `.mcp.json` in the current folder — wires three MCP servers: `fluent-mcp` (CLI), `fluent-mcp-extn` (45 tools), `chrome-devtools` (browser)
3. Checks prerequisites and reports any issues

**Alternative install paths:**

- **Skills only first:** `npx @fluentcommerce/ai-skills install`
- **Codex user install:** `npx @fluentcommerce/ai-skills install --target codex`
- **Codex project-local install:** `npx @fluentcommerce/ai-skills install --target codex --scope project`
- **Codex global MCP setup:** `npx @fluentcommerce/ai-skills mcp-setup --target codex --scope user --profile MY_PROFILE`
- **Add MCP later:** `npx @fluentcommerce/ai-skills mcp-setup --profile MY_PROFILE`
- **Faster MCP startup:** `npx @fluentcommerce/ai-skills install --profile MY_PROFILE --install-mcp-extn`
- **Optional browser / hosting MCPs:** see [`docs/mcp-servers.md`](docs/mcp-servers.md)

Use the one-command `install --profile ... --profile-retailer ...` path when you want everything wired immediately. Use `install` plus `mcp-setup` when you want to install Claude skills first and connect MCP servers later.

> **Using Codex instead of Claude Code?** Use `--target codex` to install skills into Codex’s `~/.codex/skills` runtime path. User installs are also mirrored to `~/.agents/skills` for compatibility with older layouts. This is currently **skills-only**: Claude-specific agents and slash commands like `/fluent-connect` are not installed for Codex. The installer also generates per-skill `agents/openai.yaml` metadata for Codex UI labels and invocation policy. For global MCP servers in Codex, run `mcp-setup --target codex --scope user` to update `~/.codex/config.toml`.

After running, your folder contains:

```
my-fluent-workspace/
├── .mcp.json      <- MCP server config (tells your MCP-capable IDE how to reach Fluent APIs)
└── knowledge/     <- Platform knowledge docs (domain model, SDK reference, patterns)
```

**What's global vs what's local:**

| Installed where | What | Persists across workspaces? |
|---|---|---|
| **Global** (`~/.claude/`) | Fluent skills — domain knowledge, slash commands, agents | Yes — available in every workspace |
| **Global** (`~/.codex/skills`) | Fluent Codex skills (experimental, skills-only; mirrored to `~/.agents/skills`) | Yes — available in every workspace |
| **Local** (`.agents/skills`) | Fluent Codex skills for this workspace only (`--target codex --scope project`) | No — one per workspace |
| **Local** (this folder) | `.mcp.json` — MCP server config pointing to your Fluent account | No — one per workspace |
| **Local** (this folder) | `knowledge/` — platform knowledge (domain model, SDK patterns, rule contracts) | No — managed by installer, refreshed on reinstall |
| **Local** (this folder) | `CLAUDE.md` — starter workspace instructions (auto-generated, safe to edit; [details](#claudemd-workspace-instructions)) | No — one per workspace |
| **Local** (this folder) | `accounts/` — workflows, features, source code (created in Step 3) | No — one per workspace |

You can have multiple workspaces (e.g., one per client) each with different profiles and retailers. Skills are shared; everything else is workspace-specific.

### Verify the installation

**Run `doctor` — it checks everything in one shot:**

```bash
npx @fluentcommerce/ai-skills doctor
```

`doctor` validates: Node.js version, Fluent CLI installed, Claude Code installed, skills installed, `.mcp.json` present with correct server config, `knowledge/` docs present, Fluent CLI profile exists and can authenticate, and MCP extension reachable. Fix anything it flags before proceeding.

**Quick status check (skills only):**

```bash
npx @fluentcommerce/ai-skills status
```

Shows which skill groups are installed and their install method (marketplace or file-copy). If something is missing, re-run `npx @fluentcommerce/ai-skills install --profile MY_PROFILE --profile-retailer "My Retailer"`.

**If you need to wire MCP separately** (e.g., changed profile, new workspace, or skipped `--profile` during install):

```bash
npx @fluentcommerce/ai-skills mcp-setup --profile MY_PROFILE
```

This generates `.mcp.json` in the current folder pointing to your Fluent account. Without it, the AI has no live API access.

To verify MCP servers are actually **reachable** (run inside Claude Code chat, not in terminal):
```
"Test my MCP connection"    → AI calls health_ping, confirms live API access
```

> **IMPORTANT — Restart required:** If Claude Code was already running, **quit and relaunch it** before Step 3. MCP servers only connect at startup. Without a restart, Claude Code won't see the MCP tools and API calls will fail.

---

### Step 3 — Open Claude Code and connect

Launch Claude Code **in your workspace folder**:

```bash
claude    # starts Claude Code in the current directory
```

Then type this **slash command** in the Claude Code chat:

```
/fluent-connect --profile MY_PROFILE --retailer "My Retailer"
```

> Slash commands like `/fluent-connect` are typed in the AI chat, not in a terminal. Claude Code recognizes them and runs the corresponding skill.

This creates the full `accounts/` directory tree, downloads all workflows from your Fluent account, scans any source repos you've placed, decompiles deployed JARs, and builds a full picture of what's deployed.

#### Workspace directory layout

Legend: **[auto]** = created by CLI/skills, **[you]** = you create/populate, **[ai]** = AI generates during sessions

```
<project-root>/                       <- any directory where you run the installer
+-- .mcp.json                   [auto] MCP server config (generated by install/mcp-setup)
+-- CLAUDE.md                   [auto] Starter workspace instructions (auto-generated, safe to edit)
+-- knowledge/                  [auto] Platform knowledge docs — copied from package on install
|                                      (domain model, SDK patterns, rule contracts, order patterns)
+-- accounts/
    +-- MY_PROFILE/             [auto] Created by /fluent-connect or install --profile
        |
        +-- SOURCE/              [you] YOUR implementation source code
        |   +-- backend/         [you] Clone or copy your Java plugin repos here
        |   |   +-- fc-plugin-custom/     <- your repo (git clone or cp)
        |   |   |   +-- pom.xml
        |   |   |   +-- resources/module.json
        |   |   |   +-- src/main/java/...
        |   |   +-- .decompiled/ [auto] Auto-generated from deployed JARs by /fluent-connect
        |   |
        |   +-- frontend/        [you] Clone or copy your Mystique SDK component projects here
        |       +-- mystique-appeasement/  <- your repo
        |           +-- package.json
        |           +-- src/index.tsx
        |
        +-- knowledge/           [you] Account-specific conventions (via /fluent-knowledge-init)
        |   +-- naming-conventions.md
        |   +-- coding-standards.md
        |   +-- client/
        |
        +-- workflows/          [auto] Downloaded from Fluent by /fluent-connect
        |   +-- My Retailer/
        |       +-- ORDER__HD.json       <- live workflow JSON from your account
        |       +-- workflow-context.json
        |
        +-- features/             [ai] Created by AI during feature development
        |   +-- return-order/
        |       +-- spec.md              <- from /fluent-use-case-discover
        |       +-- plan.md              <- from /fluent-feature-plan
        |       +-- architecture.md      <- from /fluent-feature-explain
        |       +-- status.json          <- lifecycle tracker (auto-updated)
        |       +-- assets/              <- screenshots, recordings, evidence
        |
        +-- memory/               [ai] Auto-accumulated learnings from your sessions
        +-- feedback/             [ai] Skill execution feedback (success/failure patterns)
        +-- reports/              [ai] Ephemeral: build/, pre-deploy/, e2e-test/
        +-- analysis/             [ai] Persistent: code/, modules/, topology/
        +-- tasks/                [ai] Operational plans (non-feature work)
        +-- sessions/             [ai] Audit trail exports
```

#### Where to put your code

| What you have | Where it goes |
|---|---|
| **Java plugin repo** (pom.xml + src/) | Clone or copy into `accounts/MY_PROFILE/SOURCE/backend/` |
| **Module JAR or reference module** (module.json + JAR) | Copy into `accounts/MY_PROFILE/SOURCE/backend/` — auto-decompiled on connect |
| **Mystique SDK project** (package.json + TypeScript) | Clone or copy into `accounts/MY_PROFILE/SOURCE/frontend/` |

You can either **clone from a Git repository** or **copy the source folder directly** — both work:

```bash
# Option A: Clone from any Git host (Bitbucket, GitHub, GitLab, etc.)
cd accounts/MY_PROFILE/SOURCE/backend
git clone <your-repo-url>

# Option B: Copy an existing source folder
cp -r /path/to/fc-plugin-custom accounts/MY_PROFILE/SOURCE/backend/
```

The workspace `.gitignore` excludes `accounts/`, so cloned repos keep their own `.git` independently.

**Adding a JAR (no source):**

```bash
cp fc-plugin-custom-1.2.3.jar accounts/MY_PROFILE/SOURCE/backend/
# Skills will auto-decompile it to .decompiled/ and extract module.json
```

**Downloading workflows (if not using /fluent-connect):**

```bash
fluent workflow download -p MY_PROFILE -r "My Retailer" -w all \
  -o accounts/MY_PROFILE/workflows/"My Retailer"/
```

---

### Step 4 — Set credentials for browser UI testing (optional)

Needed for `/fluent-ui-test`, `/fluent-ui-record`, and `/fluent-mystique-preview` to log into OMS/Store apps. Add to your shell profile (`~/.bashrc`, `~/.zshrc`, or PowerShell `$PROFILE`):

```bash
export FLUENT_USERNAME=your-username
export FLUENT_PASSWORD=your-password
```

Profile-based auth handles all Fluent API calls automatically. These are only needed for browser automation.

---

### Step 5 — Start working

Pick a starting prompt based on [who you are](#who-is-this-for):

| Persona | First prompt |
|---|---|
| 🚀 **New Starter** | `Map the implementation — what workflows, rules, and settings are deployed?` |
| 🔨 **Builder** | `Help me define use cases for return orders` |
| 🔍 **Investigator** | `Why is order HD-001 stuck in BOOKED?` |
| 📋 **Reviewer** | `Run a Ready For Launch assessment` |

The AI invokes the right skills automatically and guides you through each step.

**Complete prompt guide:** [docs/use-cases.md](docs/use-cases.md) — scenarios with exact prompts, what to expect, and artifacts created.

**Detailed walkthrough:** [docs/getting-started.md](docs/getting-started.md) — hands-on guide from setup to building your first feature end-to-end.

---

## Feature Lifecycle

Every feature follows a structured lifecycle tracked in `status.json`. The AI reads this automatically and resumes where you left off across sessions.

```
DISCOVERY ──► PLANNING ──► APPROVED ──► IN_PROGRESS ──► BUILT ──► DEPLOYED ──► VERIFIED
(spec.md)    (plan.md)    (you approve)  (building)    (build ok) (deployed)  (e2e pass)
```

**Key rule:** The AI will never make changes before presenting a plan and waiting for your approval. Say "approved" or "go ahead" to proceed; ask questions or "reject" to revise.

**Resuming work:** Say `"What features are in progress?"` or `"Continue working on return-order"` — the AI reads `status.json` and picks up exactly where it left off.

**Full lifecycle details:** [Reference Guide — Feature Lifecycle](docs/fluent-ai-skills-reference.md#6-feature-lifecycle)

### Feature Dashboard

A live HTML dashboard shows all your features with status, specs, plans, architecture diagrams, feedback metrics, and session history — updating in real-time as the AI works.

**Via AI (easiest):** Say `"Show me the feature dashboard"` — the AI sets it up and launches it automatically.

**Manual setup:**

```bash
# One-time: download vendor libs (marked.js + mermaid.js from CDN)
npx @fluentcommerce/ai-skills dashboard --setup

# Start live dashboard (auto-refreshes when files change)
npx @fluentcommerce/ai-skills dashboard --profile MY_PROFILE --serve --port 3456

# Static HTML only (no server)
npx @fluentcommerce/ai-skills dashboard --profile MY_PROFILE
```

Open `http://localhost:3456` — features appear as soon as you run `/fluent-use-case-discover`.

**Full details:** [Reference Guide — Feature Dashboard](docs/fluent-ai-skills-reference.md#feature-dashboard)

---

## Skill Groups

| Group | What it provides | Commands |
|---|---|---|
| `dev` | Full dev lifecycle — workflows, rules, modules, Mystique manifests, SDK components, UI preview, E2E testing, feature planning, debugging, monitoring | `/fluent-feature-plan`, `/fluent-workflow-builder`, `/fluent-mystique-builder`, `/fluent-e2e-test`, `...` |
| `cli` | Fluent CLI families — profile, retailer, settings, modules, workflows, bootstrap | `/fluent-connect`, `/fluent-profile`, `/fluent-workflow`, `/fluent-module-deploy`, `...` |
| `rfl` | Ready For Launch assessments | `/fluent-rfl-assess` |
| `mcp-extn` | MCP server operations — extension tools plus official CLI MCP utilities | `/fluent-mcp-tools`, `/fluent-mcp-core` |

All groups install by default. To install selectively:

```bash
npx @fluentcommerce/ai-skills install cli mcp-extn
```

### Agent Architecture

Six agents route requests automatically — you don't need to pick one:

| Agent | Role |
|---|---|
| `fluent-dev` | Orchestrator — routes to backend or frontend and owns cross-cutting lifecycle work such as planning, explain, status, E2E, and session tracking |
| `fluent-backend-dev` | Workflows, rules, modules, settings, events, deployment |
| `fluent-frontend-dev` | Manifests, SDK components, UI preview, browser UI testing |
| `fluent-cli` | CLI operations — profiles, modules, workflows, retailers |
| `fluent-mcp` | MCP tools — events, GraphQL, batch, metrics, official CLI MCP workflows |
| `fluent-rfl` | Ready For Launch assessments |

Mention "workflow", "rule", "module" for backend agent. Mention "manifest", "page", "component" for frontend agent. Both routes through the orchestrator.

Need the full routing guide? See [Agents & Skills Guide](docs/agents-and-skills-guide.md) for what each agent and skill does, how to invoke it, when to use it, and where it fits in the SDLC.

Full skill catalog with routing guide: [Reference Guide — Capability Map](docs/fluent-ai-skills-reference.md#12-appendix-capability-ownership-map)

---

## CLI Quick Reference

```bash
npx @fluentcommerce/ai-skills <command> [--profile <name>] [groups...]
```

| Command | Description |
|---|---|
| `install [groups...]` | Install skills + configure MCP (with `--profile`) |
| `doctor` | **Full setup health check** — Node, CLI, Claude Code, skills, MCP, profile, connectivity, versions |
| `status [groups...]` | Check what's installed |
| `uninstall [groups...]` | Remove installed skills |
| `mcp-setup [options]` | Generate `.mcp.json` separately |
| `flow-run [options]` | Pre-deploy diagnostics + optional guarded deploy ([details](docs/fluent-ai-skills-reference.md#9-deployment-and-promotion-runbook)) |
| `list` | List available skill groups |
| `--version` | Show version |

### Key Options

| Option | Applies to | What it does |
|---|---|---|
| `--install-mcp-extn` | `install` | Pre-install MCP extension locally (faster IDE startup — avoids npx download each time) |
| `--with-chrome` | `mcp-setup` | Add Chrome MCP Extension for manual browser debugging |
| `--save-video` | `mcp-setup` | Enable video recording for UI walkthroughs |
| `--no-browser` | `mcp-setup` | Skip Chrome DevTools setup (backend-only workflows) |

For server-by-server MCP details, auth notes, and optional hosting providers, see [`docs/mcp-servers.md`](docs/mcp-servers.md).

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| "Fluent CLI not found" | Install from [docs.fluentcommerce.com](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package) then `fluent --version` |
| "Profile directory not found" | `fluent profile create MY_PROFILE --id ... --username ... --password ... --client-secret ... --base-url ...` |
| `.mcp.json` not created | `npx @fluentcommerce/ai-skills mcp-setup --profile MY_PROFILE` |
| MCP tools return connection errors | Restart IDE, then `fluent profile retailers MY_PROFILE` to verify connectivity |
| Skills not loading in Claude Code | `npx @fluentcommerce/ai-skills doctor` (full setup health check) |
| "npx not found" | Install Node.js 20+ from [nodejs.org](https://nodejs.org) |
| Workflow deploy rejected (same version) | Always bump module version before re-deploying |
| Manifest setting not loading | Must use `valueType: "JSON"`, `context: "ACCOUNT"`, body in `lobValue` |

More detailed troubleshooting with MCP debugging steps: [Reference Guide — Troubleshooting](docs/fluent-ai-skills-reference.md#10-troubleshooting)

---

## Knowledge, Memory & Skills — Three Data Layers

The AI draws from three distinct data layers. Each has a different purpose, owner, and loading strategy:

```
┌──────────────────────────────────────────────────────────────┐
│  KNOWLEDGE (prescriptive) — "How things SHOULD work"         │
│  Owner: humans   Location: knowledge/ + accounts/<PROFILE>/knowledge/ │
│  Loading: always (CLAUDE.md refs) or on-demand (skill reads) │
├──────────────────────────────────────────────────────────────┤
│  MEMORY (descriptive) — "How things DO work"                 │
│  Owner: AI       Location: accounts/<PROFILE>/memory/        │
│  Loading: session start (index.md) + on-demand (topic files) │
├──────────────────────────────────────────────────────────────┤
│  SKILLS (executable) — "How to DO things"                    │
│  Owner: package  Location: fluent-ai-skills/content/         │
│  Loading: on invocation (/fluent-<name>)                     │
└──────────────────────────────────────────────────────────────┘
```

**When they conflict:** Knowledge wins over memory. Account knowledge (`accounts/<PROFILE>/knowledge/`) wins over generic platform knowledge (`knowledge/`).

### What goes where

| You want to capture... | Layer | File | Example |
|---|---|---|---|
| Team naming convention | **Knowledge** | `accounts/<PROFILE>/knowledge/naming-conventions.md` | "All order refs: `ORD-{storeCode}-{seq}`" |
| Platform entity model | **Knowledge** | `knowledge/platform/domain-model.md` | "ORDER has edges to fulfilments, items, customer" |
| Client routing rules | **Knowledge** | `accounts/<PROFILE>/knowledge/client/business-rules.md` | "Always warehouse-first, store fallback" |
| Deploy gotcha for this account | **Memory** | `accounts/<PROFILE>/memory/learnings.md` | "Store app needs `servicepoint` in workflow user action modules[]" |
| User working preferences | **Memory** | Global `MEMORY.md` | "User prefers concise responses" |

### How to populate

```
/fluent-knowledge-init              # Wizard asks questions, writes knowledge files
"Extract knowledge from this PDF"   # AI reads docs, writes after you confirm
Just work normally                  # AI captures corrections progressively into memory
```

**Rule of thumb:** If you'd put it in a team wiki → knowledge. If you'd tell a colleague "watch out for this" → memory. Skills are the package itself — you don't edit them.

**Full guide with format specs, loading chains, and examples:** [Data Architecture](content/knowledge/DATA-ARCHITECTURE.md) | [Knowledge Guidelines](content/knowledge/GUIDELINES.md)

### CLAUDE.md — Workspace Instructions

The installer auto-generates a starter `CLAUDE.md` in your workspace root. Claude Code reads it automatically at the start of every session. It includes:

- **Account context** — profile and retailer (pre-filled if you used `--profile`)
- **First steps** — doctor, connect, explore
- **SDLC skill map** — which skills to use at each stage (setup → discover → plan → build → deploy → test → diagnose → audit)
- **Quick actions** — common prompts and slash commands
- **Knowledge pointers** — where platform and account-specific knowledge lives
- **Conventions placeholder** — add your team-specific rules here

**The installer never overwrites an existing CLAUDE.md** — so once generated, it's yours to customize.

**What to add:**

```markdown
## Conventions
- Order refs: ORD-{storeCode}-{seq}
- All custom rules use prefix `com.client.`
- Workflow subtypes: HD, CC, SFS (no custom types)
- Always use MCP tools for GraphQL — never hardcode queries
```

**What NOT to put in it:** Don't duplicate what's already in `knowledge/` or skills. CLAUDE.md is for workspace-level overrides and team preferences.

---

## Further Reading

| Document | What's in it |
|---|---|
| [Getting Started Guide](docs/getting-started.md) | Hands-on walkthrough from setup to building your first feature |
| [Docs Index](docs/index.md) | Reading order and canonical doc map |
| [Use Cases](docs/use-cases.md) | Every capability with exact prompts, what happens, and artifacts created |
| [Agents & Skills Guide](docs/agents-and-skills-guide.md) | Consolidated routing guide for agents and skills: invocation, timing, and SDLC fit |
| [Operational Reference Guide](docs/fluent-ai-skills-reference.md) | Architecture, MCP tools, feature lifecycle, deployment runbook, workspace conventions |
| [Dev Workflow](docs/dev-workflow.md) | Full orchestration protocol with decision trees and error recovery |
| [Chrome DevTools MCP](docs/chrome-devtools-mcp-reference.md) | Browser automation patterns, selectors, and testing workflows |
| [Capability Map](docs/capability-map.md) | Which skill owns what capability, routing guide |
| [Data Architecture](content/knowledge/DATA-ARCHITECTURE.md) | Two-bucket knowledge system: generic vs account-specific — formats, loading, examples |
| [Knowledge Guidelines](content/knowledge/GUIDELINES.md) | How to set up, populate, and verify knowledge files |
| [Deployment Runbook](docs/deployment-promotion-runbook.md) | Step-by-step deployment and environment promotion |

---

## Companion Packages

| Package | Purpose |
|---|---|
| [`@fluentcommerce/fluent-mcp-extn`](https://www.npmjs.com/package/@fluentcommerce/fluent-mcp-extn) | MCP extension server — 45 tools for live API access (events, batch, metrics, settings, entities, workflows, cache) |
| [Fluent CLI](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package) | Official CLI + built-in MCP server. See [install guide](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package) |
| [`chrome-devtools-mcp`](https://www.npmjs.com/package/chrome-devtools-mcp) | Browser automation — auto-configured for `/fluent-ui-test`, `/fluent-ui-record`, and `/fluent-mystique-preview` |

---

## License

MIT
