@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/cli/skills/fluent-bootstrap/SKILL.md

@@ -1,181 +1,214 @@
----
-name: fluent-bootstrap
-description: Complete Fluent Commerce account bootstrap wizard. Use when setting up a new account from scratch, creating profiles, retailers, and installing reference modules with sample data. Triggers on "bootstrap account", "set up fluent", "new fluent account", "initialize account".
-user-invocable: true
-allowed-tools: Bash, Read, Write, Edit, Glob, Grep
-argument-hint: [profile-name] [retailer-ref]
----
-
-# Fluent Account Bootstrap
-
-Complete account setup from profile creation to sample data installation.
-
-## Planning Gate
-
-**Before bootstrapping any account, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** Account bootstrap is a high-impact operation.
-
-**Bootstrap-specific emphasis — ensure these are covered:**
-
-1. **Business Context (Section 1)** — purpose of this account; sandbox/dev/staging/prod
-2. **Scope (Section 2)** — profile name, base URL, auth method
-3. **Impacted retailers (Section 4.8)** — retailer ref, trading name, type; confirm NOT production
-4. **Detailed Design (Section 5)** — reference modules to install (with versions), sample data to load
-5. **GraphQL operations (Section 4.7)** — mutations for retailer creation, module installation
-6. **Deployment Sequence (Section 9)** — profile → retailer → modules → sample data order
-7. **Risks (Section 7)** — high-impact: confirm environment; note what's irreversible
-
-**Write the plan to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-bootstrap-<slug>.md`. Set `Status: PENDING`.
-
-Present the full plan content to the user and wait for approval before proceeding. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
-
-## When to Use
-
-- Setting up a new Fluent Commerce account from scratch
-- User asks to "bootstrap", "set up new account", "initialize fluent account"
-- Creating a complete B2C or B2B implementation environment
-
-## Prerequisites Checklist
-
-Before starting, gather:
-- [ ] Account ID
-- [ ] Base URL (e.g., `https://account.sandbox.api.fluentretail.com`)
-- [ ] Admin username & password
-- [ ] Client secret
-- [ ] Retailer reference & admin email
-
-## Cross-Platform Command Notes
-
-- Fluent CLI commands are portable across macOS, Linux, and Windows.
-- Use `rg` for placeholder scans because it works consistently in Bash, zsh, and PowerShell.
-
-## Bootstrap Workflow
-
-### Phase 1: Profile & Retailer Setup
-
-```bash
-# 1. Create profile
-fluent profile create <profile-name> \
-  --id <account-id> \
-  --base-url <base-url> \
-  --username <username> \
-  --password <password> \
-  --client-secret <client-secret>
-
-# 2. Verify profile
-fluent profile list
-fluent profile active
-
-# 3. Create retailer
-fluent retailer create <retailer-ref> \
-  --email <retailer-email> \
-  --profile <profile-name>
-
-# 4. Set active context
-fluent profile use <profile-name> --retailer <retailer-ref>
-```
-
-**Retailer creation gotchas:**
-- **Always use `fluent retailer create` CLI** — do NOT use the `createRetailer` GraphQL mutation. The mutation returns null and creates REST-only entities invisible to GraphQL. The CLI uses batch jobs to create fully-initialized retailers.
-- After creating a retailer, add a retailer-scoped admin user via `fluent profile update` so you have credentials for REST API calls and retailer-scoped events.
-- Account-level users generate CREATE events with `retailerId=0`, which causes workflow routing mismatches. Use retailer-scoped users for operations that trigger workflows.
-
-### Phase 2: Module Configuration
-
-```bash
-# Generate config templates for each module
-fluent module config core --retailer <retailer-ref> --profile <profile-name>
-fluent module config fulfilment --retailer <retailer-ref> --profile <profile-name>
-fluent module config order --retailer <retailer-ref> --profile <profile-name>
-fluent module config inventory --retailer <retailer-ref> --profile <profile-name>
-```
-
-**Generated files:** `module.config.<retailer>.<module>.json`
-
-**Common config tokens (placeholder -> example value):**
-
-| Token | Example Value | Used By |
-|-------|---------------|---------|
-| `[[retailer.id]]` | `1` | order, fulfilment, inventory |
-| `[[productCatalogue.ref]]` | `PC:MASTER:1` | order |
-| `[[network.ref.hd]]` | `B2C_HD_1` | order (home delivery routing) |
-| `[[network.ref.cc]]` | `B2C_CC_1` | order (click & collect routing) |
-| `[[virtualCatalogue.ref]]` | `BASE:1` | order (availability checks) |
-| `[[inventoryCatalogue.ref]]` | `DEFAULT:1` | inventory |
-| `[[order.validation.gracePeriodSeconds]]` | `3600` | order (cancel timeout) |
-
-**Check for unreplaced tokens:**
-```bash
-rg '\[\[.*\]\]' module.config.*.json
-```
-
-```powershell
-# PowerShell
-Select-String -Path "module.config.*.json" -Pattern '\[\[.*\]\]'
-```
-
-**WAIT for user to confirm configs are populated before continuing.**
-
-### Phase 3: Module Installation
-
-```bash
-# Install in dependency order
-fluent module install core --retailer <retailer-ref> --profile <profile-name>
-
-fluent module install fulfilment --retailer <retailer-ref> --profile <profile-name>
-
-fluent module install order \
-  --config module.config.<retailer>.order.json \
-  --retailer <retailer-ref> --profile <profile-name>
-
-fluent module install inventory \
-  --config module.config.<retailer>.inventory.json \
-  --retailer <retailer-ref> --profile <profile-name>
-```
-
-**Optional: Sample Data**
-```bash
-# Generate sample data config
-fluent module config https://downloads.fluentcommerce.com/v1.0.0/modules/fcx/b2c-sample-data/latest \
-  --retailer <retailer-ref> --profile <profile-name>
-
-# Install sample data (after populating config)
-fluent module install https://downloads.fluentcommerce.com/v1.0.0/modules/fcx/b2c-sample-data/latest \
-  --config module.config.<retailer>.b2c-sample-data.json \
-  --retailer <retailer-ref> --profile <profile-name>
-```
-
-### Phase 4: Verification
-
-```bash
-# Verify installed modules
-fluent module list -p <profile-name>
-
-# Verify workflows deployed
-fluent workflow list -p <profile-name> -r <retailer-ref>
-
-# Export for API testing
-fluent profile export <profile-name> --format postman --retailer <retailer-ref>
-```
-
-## Success Criteria
-
-- [ ] Profile created and active
-- [ ] Retailer created
-- [ ] All reference modules installed
-- [ ] Sample data installed (if requested)
-- [ ] Workflows visible in list
-- [ ] Postman environment exported
-
-## Common Errors
-
-| Error | Solution |
-|-------|----------|
-| Profile already exists | Use different name or `fluent profile update` |
-| Authentication failed | Verify credentials |
-| Module dependencies not met | Install `core` first, then others in order |
-| Config missing keys | Re-run `fluent module config` |
-
-## Output Artifacts
-
-- `module.config.<retailer>.*.json` - Configuration files
-- `postman.<profile>.<retailer>.environment.json` - Postman export
+---
+name: fluent-bootstrap
+description: Complete Fluent Commerce account bootstrap wizard. Use when setting up a new account from scratch, creating profiles, retailers, and installing reference modules with sample data. Triggers on "bootstrap account", "set up fluent", "new fluent account", "initialize account".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: [profile-name] [retailer-ref]
+---
+
+# Fluent Account Bootstrap
+
+Complete account setup from profile creation to sample data installation.
+
+## Planning Gate
+
+### Pre-flight: Plan Verification
+
+Before proceeding, check for an existing approved plan:
+
+1. **Search** `accounts/<PROFILE>/features/*/status.json` for an entry with `plan: "APPROVED"` that covers this bootstrap, OR check `accounts/<PROFILE>/tasks/` for a task plan with `Status: APPROVED`
+2. **If multi-artifact work** (bootstrap + custom rules + workflows): STOP. Invoke `/fluent-feature-plan` first — this skill cannot be used for multi-artifact work without a feature plan
+3. **If approved plan found:** Skip to implementation, referencing the plan's relevant sections
+4. **If no plan found:** Continue to the Planning Gate below to write a plan for this skill
+
+**Before bootstrapping any account, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** Account bootstrap is a high-impact operation.
+
+**Bootstrap-specific emphasis — ensure these are covered:**
+
+1. **Business Context (Section 1)** — purpose of this account; sandbox/dev/staging/prod
+2. **Scope (Section 2)** — profile name, base URL, auth method
+3. **Impacted retailers (Section 4.8)** — retailer ref, trading name, type; confirm NOT production
+4. **Detailed Design (Section 5)** — reference modules to install (with versions), sample data to load
+5. **GraphQL operations (Section 4.7)** — mutations for retailer creation, module installation
+6. **Deployment Sequence (Section 9)** — profile → retailer → modules → sample data order
+7. **Risks (Section 7)** — high-impact: confirm environment; note what's irreversible
+
+**Write the plan to:** `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-bootstrap-<slug>.md`. Set `Status: PENDING`.
+
+Present the full plan content to the user and wait for approval before proceeding. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
+
+> **New to Fluent CLI?** Start with `/fluent-cli-index` for a complete command reference and routing guide.
+
+## Handoff Protocol
+
+### Signals emitted by this skill
+
+| Signal | Condition | Example |
+|--------|-----------|---------|
+| `-> READY: <path>` | Account bootstrapped | `-> READY: Account HMDEV bootstrapped with retailer HM_TEST` |
+| `-> NEXT: /fluent-<skill>` | Ready for module/workflow deploy | `-> NEXT: /fluent-module-deploy` |
+| `-> BLOCKED: <reason>` | Cannot proceed | `-> BLOCKED: ENV_UNREACHABLE — Cannot connect to Fluent environment` |
+
+### Error codes
+
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| `PLAN_REQUIRED` | Bootstrap attempted without approved plan | Run `/fluent-feature-plan` first |
+| `ENV_UNREACHABLE` | Cannot connect to Fluent environment | Check credentials and profile via `/fluent-profile` |
+
+## When to Use
+
+- Setting up a new Fluent Commerce account from scratch
+- User asks to "bootstrap", "set up new account", "initialize fluent account"
+- Creating a complete B2C or B2B implementation environment
+
+## Prerequisites Checklist
+
+Before starting, gather:
+- [ ] Account ID
+- [ ] Base URL (e.g., `https://account.sandbox.api.fluentretail.com`)
+- [ ] Admin username & password
+- [ ] Client secret
+- [ ] Retailer reference & admin email
+
+## Cross-Platform Command Notes
+
+- Fluent CLI commands are portable across macOS, Linux, and Windows.
+- Use `rg` for placeholder scans because it works consistently in Bash, zsh, and PowerShell.
+
+## Bootstrap Workflow
+
+### Phase 1: Profile & Retailer Setup
+
+```bash
+# 1. Create profile
+fluent profile create <profile-name> \
+  --id <account-id> \
+  --base-url <base-url> \
+  --username <username> \
+  --password <password> \
+  --client-secret <client-secret>
+
+# 2. Verify profile
+fluent profile list
+fluent profile active
+
+# 3. Create retailer
+# FINAL CONFIRMATION — Retailer creation is IRREVERSIBLE.
+# Before executing, confirm with the user:
+#   "You are about to create retailer '<retailer-ref>' on <base-url>.
+#    This cannot be undone. Proceed? (yes/no)"
+# Only proceed after explicit "yes" confirmation.
+fluent retailer create <retailer-ref> \
+  --email <retailer-email> \
+  --profile <profile-name>
+
+# 4. Set active context
+fluent profile use <profile-name> --retailer <retailer-ref>
+```
+
+**Retailer creation gotchas:**
+- **Always use `fluent retailer create` CLI** — do NOT use the `createRetailer` GraphQL mutation. The mutation returns null and creates REST-only entities invisible to GraphQL. The CLI uses batch jobs to create fully-initialized retailers.
+- After creating a retailer, add a retailer-scoped admin user via `fluent profile update` so you have credentials for REST API calls and retailer-scoped events.
+- Account-level users generate CREATE events with `retailerId=0`, which causes workflow routing mismatches. Use retailer-scoped users for operations that trigger workflows.
+
+### Phase 2: Module Configuration
+
+```bash
+# Generate config templates for each module
+fluent module config core --retailer <retailer-ref> --profile <profile-name>
+fluent module config fulfilment --retailer <retailer-ref> --profile <profile-name>
+fluent module config order --retailer <retailer-ref> --profile <profile-name>
+fluent module config inventory --retailer <retailer-ref> --profile <profile-name>
+```
+
+**Generated files:** `module.config.<retailer>.<module>.json`
+
+**Common config tokens (placeholder -> example value):**
+
+| Token | Example Value | Used By |
+|-------|---------------|---------|
+| `[[retailer.id]]` | `1` | order, fulfilment, inventory |
+| `[[productCatalogue.ref]]` | `PC:MASTER:1` | order |
+| `[[network.ref.hd]]` | `B2C_HD_1` | order (home delivery routing) |
+| `[[network.ref.cc]]` | `B2C_CC_1` | order (click & collect routing) |
+| `[[virtualCatalogue.ref]]` | `BASE:1` | order (availability checks) |
+| `[[inventoryCatalogue.ref]]` | `DEFAULT:1` | inventory |
+| `[[order.validation.gracePeriodSeconds]]` | `3600` | order (cancel timeout) |
+
+**Check for unreplaced tokens:**
+```bash
+rg '\[\[.*\]\]' module.config.*.json
+```
+
+```powershell
+# PowerShell
+Select-String -Path "module.config.*.json" -Pattern '\[\[.*\]\]'
+```
+
+**WAIT for user to confirm configs are populated before continuing.**
+
+### Phase 3: Module Installation
+
+```bash
+# Install in dependency order
+fluent module install core --retailer <retailer-ref> --profile <profile-name>
+
+fluent module install fulfilment --retailer <retailer-ref> --profile <profile-name>
+
+fluent module install order \
+  --config module.config.<retailer>.order.json \
+  --retailer <retailer-ref> --profile <profile-name>
+
+fluent module install inventory \
+  --config module.config.<retailer>.inventory.json \
+  --retailer <retailer-ref> --profile <profile-name>
+```
+
+**Optional: Sample Data**
+```bash
+# Generate sample data config
+fluent module config https://downloads.fluentcommerce.com/v1.0.0/modules/fcx/b2c-sample-data/latest \
+  --retailer <retailer-ref> --profile <profile-name>
+
+# Install sample data (after populating config)
+fluent module install https://downloads.fluentcommerce.com/v1.0.0/modules/fcx/b2c-sample-data/latest \
+  --config module.config.<retailer>.b2c-sample-data.json \
+  --retailer <retailer-ref> --profile <profile-name>
+```
+
+### Phase 4: Verification
+
+```bash
+# Verify installed modules
+fluent module list -p <profile-name>
+
+# Verify workflows deployed
+fluent workflow list -p <profile-name> -r <retailer-ref>
+
+# Export for API testing
+fluent profile export <profile-name> --format postman --retailer <retailer-ref>
+```
+
+## Success Criteria
+
+- [ ] Profile created and active
+- [ ] Retailer created
+- [ ] All reference modules installed
+- [ ] Sample data installed (if requested)
+- [ ] Workflows visible in list
+- [ ] Postman environment exported
+
+## Common Errors
+
+| Error | Solution |
+|-------|----------|
+| Profile already exists | Use different name or `fluent profile update` |
+| Authentication failed | Verify credentials |
+| Module dependencies not met | Install `core` first, then others in order |
+| Config missing keys | Re-run `fluent module config` |
+
+## Output Artifacts
+
+- `module.config.<retailer>.*.json` - Configuration files
+- `postman.<profile>.<retailer>.environment.json` - Postman export

package/content/cli/skills/fluent-cli-index/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-cli-index
-description: Master router for Fluent Commerce CLI tasks. Classifies requests by CLI command family and delegates to the right Fluent CLI skill (profile, retailer, module, workflow, settings, bootstrap, and MCP setup). Use when users ask broad Fluent CLI questions or mixed CLI tasks.
+description: Master router for Fluent Commerce CLI tasks. Classifies requests by CLI command family and delegates to the right Fluent CLI skill (profile, retailer, module, workflow, settings, bootstrap, and MCP setup). Use when users ask broad Fluent CLI questions or mixed CLI tasks. Triggers on "fluent cli", "cli help", "how do I use fluent", "which cli command", "cli overview".
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [request-summary] [--profile name] [--retailer ref]

package/content/cli/skills/fluent-cli-mcp-cicd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fluent-cli-mcp-cicd
-description: Fluent CLI MCP and CI/CD operations guide. Use for configuring `fluent mcp server --stdio`, validating MCP connectivity, and applying safe module deployment patterns in automation pipelines.
+description: Fluent CLI MCP and CI/CD operations guide. Use for configuring `fluent mcp server --stdio`, validating MCP connectivity, and applying safe module deployment patterns in automation pipelines. Triggers on "mcp cicd", "ci cd pipeline", "automation pipeline", "mcp server setup", "fluent mcp stdio".
 user-invocable: true
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep
 argument-hint: [mcp|cicd] [--profile name] [--retailer ref]
@@ -10,6 +10,8 @@ argument-hint: [mcp|cicd] [--profile name] [--retailer ref]
 
 Configure the official Fluent MCP server via CLI and apply guardrails for CI/CD module delivery.
 
+> **New to Fluent CLI?** Start with `/fluent-cli-index` for a complete command reference and routing guide.
+
 ## When to Use
 
 - User asks to enable `fluent mcp` in an IDE/client
@@ -68,6 +70,120 @@ npx @fluentcommerce/ai-skills flow-run \
   --deploy --yes
 ```
 
+## CI/CD Pipeline Templates
+
+### GitHub Actions
+
+```yaml
+name: Fluent Module Deploy
+on:
+  push:
+    branches: [main]
+    paths: ['plugins/**', 'resources/**']
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with: { distribution: temurin, java-version: 17 }
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with: { node-version: 20 }
+
+      - name: Install Fluent CLI
+        run: npm i -g @fluentcommerce/cli
+
+      - name: Create profile
+        run: |
+          fluent profile create deploy-target \
+            --id ${{ secrets.FLUENT_ACCOUNT_ID }} \
+            --base-url ${{ secrets.FLUENT_BASE_URL }} \
+            --username ${{ secrets.FLUENT_USERNAME }} \
+            --password ${{ secrets.FLUENT_PASSWORD }} \
+            --client-secret ${{ secrets.FLUENT_CLIENT_SECRET }}
+
+      - name: Build module
+        run: cd plugins && mvn clean install -q
+
+      - name: Pre-deploy diagnostics
+        run: |
+          npx @fluentcommerce/ai-skills flow-run \
+            --profile deploy-target \
+            --retailer ${{ vars.RETAILER_REF }} \
+            --module dist/module.zip
+
+      - name: Deploy module
+        run: |
+          fluent module install dist/module.zip \
+            -p deploy-target \
+            -r ${{ vars.RETAILER_REF }}
+```
+
+### GitLab CI
+
+```yaml
+fluent-deploy:
+  image: node:20
+  stage: deploy
+  only:
+    changes: [plugins/**, resources/**]
+  before_script:
+    - npm i -g @fluentcommerce/cli
+    - apt-get update && apt-get install -y maven
+  script:
+    - fluent profile create deploy-target --id $FLUENT_ACCOUNT_ID --base-url $FLUENT_BASE_URL --username $FLUENT_USERNAME --password $FLUENT_PASSWORD --client-secret $FLUENT_CLIENT_SECRET
+    - cd plugins && mvn clean install -q && cd ..
+    - npx @fluentcommerce/ai-skills flow-run --profile deploy-target --retailer $RETAILER_REF --module dist/module.zip
+    - fluent module install dist/module.zip -p deploy-target -r $RETAILER_REF
+```
+
+**Key principles:**
+- Never store credentials in pipeline files — use CI/CD secrets/variables
+- Always run `flow-run` (diagnostics) before `module install` (deploy)
+- Separate build and deploy stages for rollback granularity
+- Use `--yes` flag only after diagnostics pass
+
+## CI/CD Pipeline Template
+
+Minimal GitHub Actions workflow for module validation and deployment:
+
+```yaml
+name: Fluent Deploy
+on:
+  push:
+    branches: [main]
+    paths: ['modules/**']
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: '20' }
+      - run: npm install -g @fluentcommerce/cli
+      - name: Validate
+        run: fluent module validate --path ${{ github.workspace }}/modules/$MODULE_NAME
+      - name: Pre-deploy check
+        run: |
+          npx @fluentcommerce/ai-skills flow-run --profile $FLUENT_PROFILE --retailer $RETAILER_REF --check pre-deploy
+      - name: Deploy (requires explicit approval)
+        if: github.ref == 'refs/heads/main'
+        run: |
+          fluent module install --path ${{ github.workspace }}/modules/$MODULE_NAME -p $FLUENT_PROFILE -r $RETAILER_REF
+    env:
+      FLUENT_PROFILE: ${{ secrets.FLUENT_PROFILE }}
+      RETAILER_REF: ${{ secrets.RETAILER_REF }}
+      MODULE_NAME: ${{ vars.MODULE_NAME }}
+```
+
+Adapt for GitLab CI by replacing `jobs:` with `stages:` and `steps:` with `script:`. The key principle is: validate -> pre-deploy-check -> deploy, with explicit approval gates between stages.
+
 ## Troubleshooting
 
 | Issue | Likely Cause | Fix |