# Getting Started with Fluent AI Skills

> [!CAUTION]
> **🧪 EXPERIMENTAL — LABS PROJECT**
> This package is not production-ready. No stability guarantees, no support, no warranty. See [README](../README.md) for full disclaimer.

A hands-on walkthrough for first-time users of `@fluentcommerce/ai-skills`. Follow along to go from zero to productive in under 10 minutes, then build a complete feature end-to-end.

---

## Table of Contents

- [1. Prerequisites](#1-prerequisites)
- [2. Install and Connect (5 Minutes to Productive)](#2-install-and-connect-5-minutes-to-productive)
- [3. Pick Your Starting Path](#3-pick-your-starting-path)
- [4. Your First Debug: Finding Why an Order is Stuck](#4-your-first-debug-finding-why-an-order-is-stuck)
- [5. Building a Feature End-to-End (The Full Lifecycle)](#5-building-a-feature-end-to-end-the-full-lifecycle)
- [6. Quick Tasks (No Feature Lifecycle)](#6-quick-tasks-no-feature-lifecycle)
- [7. Resuming Work Across Sessions](#7-resuming-work-across-sessions)
- [8. The Approval Gate (How the AI Asks Permission)](#8-the-approval-gate-how-the-ai-asks-permission)
- [9. Quick Reference: Common Prompts](#9-quick-reference-common-prompts)
- [10. Troubleshooting](#10-troubleshooting)
- [11. Next Steps](#11-next-steps)

---

## 1. Prerequisites

| Requirement | How to check |
|-------------|-------------|
| Node.js 18+ | `node --version` |
| Fluent CLI installed | `fluent --version` (install from [docs.fluentcommerce.com](https://docs.fluentcommerce.com/building-blocks/fluent-cli-package)) |
| A Fluent Commerce account | Base URL, credentials, and a retailer to work with |
| A Fluent CLI profile configured | `fluent profile create YOUR_PROFILE --id <id> --username <user> --password <pass> --client-secret <secret> --base-url <url>` |
| Claude Code | The supported AI IDE |

See the [README](../README.md) for full installation details.

---

## 2. Install and Connect (5 Minutes to Productive)

Two steps get you from nothing to a connected, skill-enabled workspace.

**Step 1 -- Install skills + configure MCP (one command):**

```bash
npx @fluentcommerce/ai-skills install --profile YOUR_PROFILE --profile-retailer YOUR_RETAILER
```

This single command:
- Installs all Fluent skill groups into your IDE (Claude Code marketplace plugin, or file-copy fallback)
- Auto-generates `.mcp.json` with three MCP servers: `fluent-mcp` (official CLI), `fluent-mcp-extn` (45 extension tools), and `chrome-devtools` (browser UI testing). Optionally add Chrome MCP Extension with `--with-chrome` for manual debugging
- Checks prerequisites (Fluent CLI, profile directory, npx) and reports any issues

**Don't have a Fluent profile yet?** Install skills first, add MCP later:

```bash
npx @fluentcommerce/ai-skills install                                     # skills only
fluent profile create YOUR_PROFILE --id <id> --username <user> --password <pass> --client-secret <secret> --base-url <url>
npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE            # add MCP config
```

**Want faster MCP server startup?** Add `--install-mcp-extn`:

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

This pre-installs `@fluentcommerce/fluent-mcp-extn` locally so the MCP server starts instantly instead of downloading via npx on each IDE start.

**Step 2 -- Connect to your account** (in Claude Code):

```
/fluent-connect
```

Discovers CLI profiles, selects the retailer, downloads all workflows, scans source code, decompiles deployed JARs, builds a rule inventory, and persists workspace state. After this, the AI has full context about your implementation.

**Workspace after connect:**

```
accounts/<PROFILE>/
  SOURCE/                          <-- All implementation source code
    backend/                       <-- Java Maven plugin repos (README.md)
    frontend/                      <-- Mystique SDK component projects (README.md)
  workflows/<RETAILER>/            <-- downloaded workflow JSONs
    ORDER__HD.json
    workflow-context.json          <-- download metadata
  features/                        <-- Feature lifecycle dirs (README.md)
  tasks/                           <-- Operational plans (README.md)
  reports/                         <-- Ephemeral run outputs (README.md)
  analysis/                        <-- Persistent analysis artifacts (README.md)
  feedback/                        <-- Skill execution feedback (README.md)
  sessions/                        <-- Audit trail exports (README.md)
  settings/backups/                <-- Setting backups (README.md)
  manifests/backups/               <-- Manifest backups (README.md)
  knowledge/                       <-- Account-specific knowledge overrides (README.md)
  workspace-state.json             <-- cached state
```

Each directory includes a `README.md` explaining its purpose and which skills populate it. Created only if missing (idempotent).

---

## 3. Pick Your Starting Path

Different people need different starting points. Find your persona and jump in:

| Persona | Your first session | Section |
|---|---|---|
| 🚀 **New Starter** — just joined, need context | Map the implementation, then explore features | Start here ↓ then [§4](#4-your-first-debug-finding-why-an-order-is-stuck) |
| 🔨 **Builder** — ready to implement | Gather requirements, plan, build | Jump to [§5](#5-building-a-feature-end-to-end-the-full-lifecycle) |
| 🔍 **Investigator** — debugging an issue | Trace the stuck order, check events | Jump to [§4](#4-your-first-debug-finding-why-an-order-is-stuck) |
| 📋 **Reviewer** — auditing before go-live | Run RFL assessment, map implementation | Jump to [§6](#6-quick-tasks-no-feature-lifecycle) |

> See the [README — Who Is This For?](../README.md#who-is-this-for) for full persona descriptions with example prompts.

---

## 3a. Understanding What is Built

**Type this:**

```
Explain how Home Delivery works end-to-end
```

**What the AI does:** Reads all workflow JSONs under `accounts/<PROFILE>/workflows/<RETAILER>/`, queries the live environment for deployed rules via `plugin.list`, maps state machines for each entity (ORDER, FULFILMENT_CHOICE, FULFILMENT), cross-references settings and webhooks, and generates Mermaid diagrams.

**What is created:**

```
accounts/<PROFILE>/features/home-delivery/
  architecture.md    <-- Feature Architecture Document with diagrams, rules, settings
  status.json        <-- { "status": "DISCOVERY", "architecture": true }
```

Open `architecture.md` to find state machine diagrams, cross-entity sequence diagrams, a rules table explaining what each ruleset does, settings dependencies with live values, and integration points (webhooks, carrier APIs, WMS). This is read-only -- no planning gate, no environment changes.

---

## 4. Your First Debug: Finding Why an Order is Stuck

**Type this:**

```
Why is order HD-12345 stuck in BOOKED?
```

**What the AI does:** Queries event history for `HD-12345` via `event.list`, inspects recent events with `event.flowInspect` for rule execution details, checks for NO_MATCH conditions and rule exceptions, cross-references the workflow definition, and presents root cause analysis with remediation.

**Example investigation flow:**

```
event.list(entityRef: "HD-12345")
  --> last event: "OrderBooked"
event.flowInspect(eventId: "...")
  --> ruleset "on.booked.allocate" matched, but rule "AllocateFromNetwork"
      threw NullPointerException
Root cause: No fulfilment locations in the retailer's network
Remediation: Create locations via /fluent-retailer-config, re-send event
```

The AI provides actionable next steps -- not just the diagnosis but what to do about it.

---

## 5. Building a Feature End-to-End (The Full Lifecycle)

We will build a **return order** feature from requirements through deployment. Each step shows what to type, what happens, and what is created.

### Step 1: Gather Requirements

```
Help me define use cases for return orders
```

Launches an interactive requirements wizard. Asks about triggers, business rules, entities, and edge cases. Produces a Business Spec at `accounts/<PROFILE>/features/return-order/spec.md` with `status.json` tracking the lifecycle. The AI presents the spec for review -- say `"approved"` to lock it.

### Step 1.5: Phase the Feature (optional — complex features only)

```
Phase this feature into delivery slices
```

For large features (8+ rules, 3+ workflows, or 3+ entity types), decompose the spec into independently deployable vertical slices. Each phase delivers end-to-end value and can be tested before moving on. Produces `accounts/<PROFILE>/features/<slug>/phases.md`. Skip this for simple features — go straight to Step 2.

### Step 2: Plan the Feature

```
Plan the return order feature
```

Reads the approved spec (and phases.md if present — scopes the plan to the current phase), analyzes existing workflows and rules, and produces an 18-section plan with Mermaid diagrams, rules inventory, workflow state machines, settings, risk assessment, and test plan. Created at `accounts/<PROFILE>/features/return-order/plan.md`.

### Step 3: Approve the Plan

```
Approved
```

Marks the plan as approved. `status.json` now looks like this:

```json
{
  "$schema": "feature-status-v2",
  "feature": "return-order",
  "retailers": ["MY_RETAILER"],
  "status": "APPROVED",
  "spec": "APPROVED",
  "plan": "APPROVED",
  "build": null,
  "deploy": null,
  "planRevision": 1,
  "architecture": false,
  "next": "/fluent-module-scaffold"
}
```

| Field | Meaning |
|-------|---------|
| `status` | Overall progress: DISCOVERY -> PLANNING -> APPROVED -> IN_PROGRESS -> BUILT -> DEPLOYED -> VERIFIED |
| `spec` / `plan` | Each artifact tracks its own state: null -> DRAFT -> APPROVED |
| `build` / `deploy` | Gate fields: null -> PENDING -> PASSED/DEPLOYED or FAILED |
| `planRevision` | Version counter -- increments if plan is revised |
| `next` | Which skill the AI runs next (auto-determined) |

### Step 4: Scaffold the Module

```
Scaffold the module
```

Creates a Maven project skeleton at `accounts/<PROFILE>/SOURCE/backend/fc-module-my-returns/` with `pom.xml`, `module.json`, and source directories.

### Step 5: Create the Rules

```
Create the rules from the plan
```

Scaffolds Java rule classes with pseudo logic from the plan, generates test classes, and registers rules in `module.json`:

```
accounts/<PROFILE>/SOURCE/backend/fc-module-my-returns/
  plugins/rules/my-returns/
    src/main/java/.../ValidateReturnWindow.java
    src/main/java/.../CreateReturnFulfilment.java
    src/main/java/.../CalculateRefundAmount.java
    src/test/java/.../ValidateReturnWindowTest.java
    src/test/java/.../CreateReturnFulfilmentTest.java
    src/test/java/.../CalculateRefundAmountTest.java
  resources/module.json              <-- rules registered here
```

### Step 6: Build the Workflow

```
Build the workflow from the plan
```

Constructs the workflow JSON with statuses, rulesets, rules, and event triggers. Validates with `/fluent-workflow-analyzer` for orphaned rulesets and trigger conflicts. Created at `accounts/<PROFILE>/workflows/<RETAILER_REF>/RETURN_ORDER__DEFAULT.json`.

### Step 7: Build the Module

```
Build the module
```

Runs module validation, then Maven build. Produces `accounts/<PROFILE>/SOURCE/backend/fc-module-my-returns/dist/fc-module-my-returns-1.0.0.zip`.

### Step 8: Run Pre-Deploy Checks

```
Run pre-deploy checks
```

Executes 26 quality gates across 8 phases -- module structure, rule registrations, workflow references, settings, version consistency. Produces a GO/NO-GO report at `accounts/<PROFILE>/reports/pre-deploy/my-returns-pre-deploy.json`.

### Step 9: Deploy

```
Deploy to MY_RETAILER
```

Deploys the module ZIP, then uploads the workflow JSON. Confirms each step before executing. Module `fc-module-my-returns` and workflow `RETURN_ORDER__DEFAULT` are now live.

### Step 10: Run E2E Tests

```
Run E2E test
```

Creates test entities, sends events, polls for expected status transitions, reports pass/fail per scenario from the plan's test plan.

**Final workspace layout:**

```
accounts/<PROFILE>/
  features/return-order/
    status.json                                      <-- status: VERIFIED
    spec.md                                          <-- business requirements
    plan.md                                          <-- approved plan
    assets/                                          <-- screenshots, recordings, evidence
  SOURCE/backend/fc-module-my-returns/
    resources/module.json                            <-- rule registrations
    plugins/rules/my-returns/
      src/main/java/.../ValidateReturnWindow.java
      src/main/java/.../CreateReturnFulfilment.java
      src/main/java/.../CalculateRefundAmount.java
      src/test/java/...                              <-- matching tests
    dist/fc-module-my-returns-1.0.0.zip              <-- built module
  workflows/<RETAILER_REF>/
    RETURN_ORDER__DEFAULT.json                       <-- deployed workflow
  reports/pre-deploy/
    my-returns-pre-deploy.json                       <-- quality gate results
```

---

## 6. Quick Tasks (No Feature Lifecycle)

Not everything requires the full lifecycle. One-off tasks use standalone plan files in `accounts/<PROFILE>/tasks/`.

**Scaffold a single rule:**

```
Create a rule called CancelOrderRule that cancels an order and notifies the customer
```

Creates a task plan at `accounts/<PROFILE>/tasks/2026-02-24-rule-scaffold-cancel-order.md`, presents it for approval, then scaffolds the Java class and test into the appropriate module.

**Deploy a single workflow:**

```
Deploy ORDER__HD to MY_RETAILER
```

Runs pre-deploy checks, confirms the target, and uploads the workflow JSON directly. No feature directory created.

**Audit settings:**

```
Audit settings for ORDER__HD
```

Reads the workflow, identifies settings references, queries live values, and reports missing, unexpected, or unused settings. Read-only -- nothing changed.

---

## 7. Resuming Work Across Sessions

The AI persists progress in `status.json` files and reads them to resume where you left off.

**Check what is in progress:**

```
What features are in progress?
```

Scans `accounts/<PROFILE>/features/*/status.json` for any feature not yet `VERIFIED`.

**Resume a feature:**

```
Continue working on return orders
```

The AI reads `accounts/<PROFILE>/features/return-order/status.json`, finds the `next` field (e.g., `"/fluent-build"`), and picks up from that step:

```
AI reads status.json --> status: IN_PROGRESS, next: /fluent-build
AI: "The return order feature has an approved plan. Rules are scaffolded.
     Next step is to build the module. Shall I proceed?"
```

---

## 8. The Approval Gate (How the AI Asks Permission)

The AI never makes changes without asking first:

1. **Presents a plan** -- structured markdown with diagrams, rules, risks, and test plan
2. **Waits for review** -- you can ask questions, request changes, or reject
3. **You approve** -- say `"approved"`, `"yes"`, `"go ahead"`, or `"do it"`
4. **Implementation begins** -- the AI follows the plan step by step

**Triggers the gate:** Any change to code, workflows, settings, or the live environment.

**Skips the gate:** Read-only operations (explain, trace, analyze, audit, diagnose).

**Override:** Say `"just do it"` or `"skip planning"` to bypass the gate entirely (logged as user override).

---

## 9. Quick Reference: Common Prompts

| I want to... | Say this |
|--------------|---------|
| Connect to my Fluent account | `/fluent-connect` |
| Understand an existing feature | `"Explain how Home Delivery works end-to-end"` |
| Gather requirements for a new feature | `"Help me define use cases for curbside pickup"` |
| Plan a multi-artifact feature | `"Plan the curbside pickup feature"` |
| Debug a stuck order | `"Why is order HD-001 stuck in BOOKED?"` |
| Scaffold a new module | `"Scaffold a new module called my-returns"` |
| Scaffold a new rule | `"Create a rule called ValidateReturnWindow"` |
| Build a workflow from a plan | `"Build the workflow from the plan"` |
| Analyze a workflow for issues | `"Analyze ORDER__HD for orphaned rulesets"` |
| Build and package a module | `"Build the my-extensions module"` |
| Run pre-deploy quality gates | `"Run pre-deploy checks for my-returns"` |
| Deploy a module | `"Deploy my-returns to MY_RETAILER"` |
| Deploy a workflow | `"Deploy ORDER__HD to MY_RETAILER"` |
| Run end-to-end tests | `"Run E2E test for the return order flow"` |
| Audit settings for a workflow | `"What settings are missing for ORDER__HD?"` |
| Check what is in progress | `"What features are in progress?"` |
| Resume a previous feature | `"Continue working on return orders"` |
| Check event health | `"Show event failure rates for the last hour"` |
| Create test data | `"Create a test HD order"` |
| Verify UI in browser | `"Test the OMS orders page in the browser"` |
| See what skills ran this session | `"What skills ran? Show the decision chain"` |

---

## 10. Troubleshooting

### MCP tools not working

**Symptom:** The AI cannot reach the Fluent environment, or tool calls return connection errors.

**Diagnostic checklist:**

```bash
# 1. Verify Fluent CLI
fluent --version                          # should print version; if not: https://docs.fluentcommerce.com/building-blocks/fluent-cli-package

# 2. Verify profile
ls ~/.fluentcommerce/YOUR_PROFILE/        # should exist; if not: fluent profile create YOUR_PROFILE ...
fluent profile retailers YOUR_PROFILE     # should list retailers for this profile

# 3. Verify .mcp.json
cat .mcp.json                             # should have fluent-mcp, fluent-mcp-extn, and chrome-devtools entries

# 4. Test MCP extension server (starts on stdio — Ctrl+C to exit)
npx @fluentcommerce/fluent-mcp-extn           # should print startup banner; if not: check Node.js 20+

# 5. Test official MCP server
fluent mcp server --stdio                 # should start (Ctrl+C to exit)

# 6. Regenerate MCP config
npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE

# 7. Restart your IDE — MCP servers initialize at startup
```

**Quick fix:** Re-run the install with `--profile` to regenerate everything:
```bash
npx @fluentcommerce/ai-skills install --profile YOUR_PROFILE --profile-retailer YOUR_RETAILER
```

### No workflows found

**Symptom:** The AI reports no workflows available for analysis.

**Fix:**
1. Run `/fluent-connect` to download workflows from the live environment
2. Or manually: `fluent workflow download -p YOUR_PROFILE -r YOUR_RETAILER -w all -o accounts/YOUR_PROFILE/workflows/YOUR_RETAILER/`
3. Check `accounts/<PROFILE>/workflows/<RETAILER>/` for `*.json` files

### "Plan required" error

**Symptom:** The AI refuses to scaffold, build, or deploy and says a plan is required.

**Fix:** The approval gate is working as intended. Either:
- Say `"Plan the <feature-name> feature"` to generate a plan, then `"approved"`
- Say `"just do it"` to bypass the gate (logged as override)

### Rule not found in workflow

**Symptom:** A workflow references a custom rule the environment does not recognize.

**Fix:** Deploy the module before the workflow:
1. `"Build the my-returns module"` -- compile and package
2. `"Deploy my-returns to MY_RETAILER"` -- install on the account
3. `"Deploy RETURN_ORDER__DEFAULT to MY_RETAILER"` -- now the rules are available

### Skills not loading after install

**Symptom:** The AI does not recognize Fluent commands or slash commands.

**Fix:**
1. Verify: `npx @fluentcommerce/ai-skills status`
2. Restart your IDE — skills load at startup
3. For Claude Code with marketplace: check `~/.claude/plugins/installed_plugins.json`
4. For Claude Code with file-copy: check that `~/.claude/agents/` and `~/.claude/skills/` have fluent content
5. Re-install: `npx @fluentcommerce/ai-skills install`

### Chrome DevTools MCP not working (for `/fluent-ui-test`)

**Symptom:** The AI reports "Chrome DevTools MCP not connected" when you try to test a page in the browser.

**Fix:**
1. Verify `.mcp.json` has a `chrome-devtools` server entry:
   ```json
   "chrome-devtools": {
     "command": "npx",
     "args": ["-y", "chrome-devtools-mcp@latest"],
     "env": {
       "FLUENT_UI_BASE_URL": "https://<account>.<env>.apps.engineering.fluentcommerce.com"
     }
   }
   ```
2. Restart your IDE — MCP servers initialize at startup
3. Verify `npx chrome-devtools-mcp@latest` runs without errors
4. Check that the `FLUENT_UI_BASE_URL` points to the correct account and environment

### Chrome MCP Extension not working (optional `--with-chrome`)

**Symptom:** Chrome MCP tools are not available after running `mcp-setup --with-chrome`.

**Fix:**
1. Install the Chrome extension from https://github.com/hangwin/mcp-chrome (load unpacked or install from release)
2. Enable the extension in Chrome and keep Chrome open
3. Verify the extension is listening on port 12306 (default)
4. Verify `.mcp.json` has a `chrome-manual` entry with `mcp-chrome-bridge` in args
5. Restart your IDE — MCP servers initialize at startup

**Note:** Chrome MCP is optional and opt-in. If you don't need manual debugging with existing Chrome sessions, skip it. Chrome DevTools MCP covers all automated testing needs.

---

## 11. Next Steps

| Resource | What it covers |
|----------|---------------|
| [index.md](index.md) | Docs hub and recommended reading order |
| [use-cases.md](use-cases.md) | 21 detailed scenarios from onboarding to go-live readiness |
| [dev-workflow.md](dev-workflow.md) | The full autonomous development protocol (analyze, plan, build, deploy, test loop) |
| [README.md](../README.md) | CLI reference, install options, MCP setup details |
| [Agents & Skills Guide](agents-and-skills-guide.md) | What each agent and skill does, how to invoke it, when to use it, and where it fits in the SDLC |
| [Operational Reference](fluent-ai-skills-reference.md) | Architecture, MCP tools, feature lifecycle, deployment runbook, CLI reference |
| [Capability Map](capability-map.md) | Which skill owns what capability, routing guide |
| [Chrome DevTools MCP](chrome-devtools-mcp-reference.md) | Browser automation, testing workflows, Material UI selectors, click telemetry |
| [Deployment Runbook](deployment-promotion-runbook.md) | Step-by-step deployment and environment promotion guide |
