@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/docs/GETTING_STARTED.md

@@ -0,0 +1,427 @@
+# Getting Started with Fluent AI Skills
+
+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. Your First Task: Understanding What is Built](#3-your-first-task-understanding-what-is-built)
+- [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 with `npm i -g @fluentcommerce/cli`) |
+| A Fluent Commerce account | Base URL, credentials, and a retailer to work with |
+| A Fluent CLI profile configured | `fluent auth login -p YOUR_PROFILE` |
+| Claude Code (or another supported IDE) | Primary target; Cursor, Copilot, Windsurf, Codex, Gemini also supported |
+
+See the [README](../README.md) for full installation options and supported targets.
+
+---
+
+## 2. Install and Connect (5 Minutes to Productive)
+
+Three commands get you from nothing to a connected, skill-enabled workspace.
+
+**Step 1 -- Install skills into your IDE:**
+
+```bash
+npx @fluentcommerce/ai-skills install
+```
+
+Copies Fluent-specific skill files and agent definitions into your IDE's native format. For Claude Code, files go to `~/.claude/agents/` and `~/.claude/skills/`.
+
+**Step 2 -- Configure MCP server connections:**
+
+```bash
+npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE
+```
+
+Generates a `.mcp.json` in your project root with entries for the official Fluent CLI MCP server and the extension MCP server. These give the AI live access to your Fluent environment -- GraphQL, events, settings, deployments.
+
+**Step 3 -- 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/                          <-- cloned or discovered source repos
+  workflows/<RETAILER>/            <-- downloaded workflow JSONs
+    ORDER__HD.json
+    workflow-context.json          <-- download metadata
+  analysis/                        <-- generated artifacts
+  workspace-state.json             <-- cached state
+```
+
+---
+
+## 3. Your First Task: 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 2: Plan the Feature
+
+```
+Plan the return order feature
+```
+
+Reads the approved spec, 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-v1",
+  "feature": "return-order",
+  "retailer": "HM_TEST",
+  "status": "APPROVED",
+  "spec": "APPROVED",
+  "plan": "APPROVED",
+  "planRevision": 1,
+  "architecture": false,
+  "next": "/fluent-module-scaffold"
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `status` | Overall progress: DISCOVERY -> PLANNING -> APPROVED -> IN_PROGRESS -> VERIFIED -> ARCHIVED |
+| `spec` / `plan` | Each artifact tracks its own state: null -> DRAFT -> APPROVED |
+| `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/fc-module-hm-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/fc-module-hm-returns/
+  plugins/rules/hm-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/HM_TEST/RETURN_ORDER__DEFAULT.json`.
+
+### Step 7: Build the Module
+
+```
+Build the module
+```
+
+Runs module validation, then Maven build. Produces `accounts/<PROFILE>/SOURCE/fc-module-hm-returns/dist/fc-module-hm-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/hm-returns-pre-deploy.json`.
+
+### Step 9: Deploy
+
+```
+Deploy to HM_TEST
+```
+
+Deploys the module ZIP, then uploads the workflow JSON. Confirms each step before executing. Module `fc-module-hm-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
+  SOURCE/fc-module-hm-returns/
+    resources/module.json                            <-- rule registrations
+    plugins/rules/hm-returns/
+      src/main/java/.../ValidateReturnWindow.java
+      src/main/java/.../CreateReturnFulfilment.java
+      src/main/java/.../CalculateRefundAmount.java
+      src/test/java/...                              <-- matching tests
+    dist/fc-module-hm-returns-1.0.0.zip              <-- built module
+  workflows/HM_TEST/
+    RETURN_ORDER__DEFAULT.json                       <-- deployed workflow
+  reports/pre-deploy/
+    hm-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 HM_TEST
+```
+
+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` or `ARCHIVED`.
+
+**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 hm-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 hm-extensions module"` |
+| Run pre-deploy quality gates | `"Run pre-deploy checks for hm-returns"` |
+| Deploy a module | `"Deploy hm-returns to HM_TEST"` |
+| Deploy a workflow | `"Deploy ORDER__HD to HM_TEST"` |
+| 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"` |
+| 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.
+
+**Fix:**
+1. Check that `.mcp.json` exists in your project root with valid entries
+2. Re-run `npx @fluentcommerce/ai-skills mcp-setup --profile YOUR_PROFILE`
+3. Restart your IDE -- MCP servers initialize at startup
+4. Verify your profile: `fluent auth verify -p YOUR_PROFILE`
+
+### 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 hm-returns module"` -- compile and package
+2. `"Deploy hm-returns to HM_TEST"` -- install on the account
+3. `"Deploy RETURN_ORDER__DEFAULT to HM_TEST"` -- 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, check that `~/.claude/` has content
+
+---
+
+## 11. Next Steps
+
+| Resource | What it covers |
+|----------|---------------|
+| [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, all install options, supported targets, MCP setup details |
+| [CAPABILITY_MAP.md](CAPABILITY_MAP.md) | Which skill owns which capability -- the definitive routing guide |
+| [FLOW_RUN.md](FLOW_RUN.md) | Automated diagnostics and guarded deployment execution |