@fluentcommerce/ai-skills 0.1.0 → 0.2.0

package/content/dev/skills/fluent-workflow-deploy/SKILL.md

@@ -1,267 +0,0 @@
----
-name: fluent-workflow-deploy
-description: Deploy Fluent Commerce workflows with validation, MCP tool primary strategy, and automatic REST API fallback. Handles pre-flight checks, upload, version verification, and rollback. Triggers on "deploy workflow", "upload workflow", "push workflow", "workflow deploy".
-user-invocable: true
-allowed-tools: Bash, Read, Write, Edit, Glob, Grep
-argument-hint: <workflow-file> [--profile <name>] [--retailer <ref>] [--dry-run]
----
-
-# Workflow Deployer
-
-Deploy Fluent Commerce workflow definitions with validation, multiple upload strategies, and automatic fallback.
-
-## Planning Gate
-
-**Before deploying any workflow, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.**
-
-**Workflow-deploy specific emphasis -- ensure these are covered:**
-
-1. **Business Context (Section 1)** -- what change this workflow update delivers
-2. **Scope (Section 2)** -- workflow name (e.g., `ORDER::HD`), current version -> new version
-3. **Rulesets (Section 6)** -- new/modified/removed rulesets with Source classification
-4. **Rules Inventory (Section 7)** -- confirm all referenced rules exist in `plugin.list`
-5. **Deployment Sequence (Section 17)** -- module deploy BEFORE workflow deploy if new custom rules are referenced
-6. **Rollback Plan (Section 18)** -- previous workflow version to restore
-
-**Write the plan to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-workflow-deploy-<slug>.md`. Set `Status: PENDING`.
-
-Present the full plan content to the user and wait for approval before uploading. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
-
-## Ownership Boundary
-
-This skill owns the deployment execution pipeline (validate -> upload -> verify -> rollback).
-
-Workflow structure and editing are owned by `/fluent-workflow-builder`.
-Workflow listing and download are owned by `/fluent-workflow`.
-Workflow analysis is owned by `/fluent-workflow-analyzer`.
-
-## Module-First Deployment — Check Before Using This Skill
-
-**If the workflow is part of a module** (exists in `resources/workflows/` within a module directory), deploy the entire module via `/fluent-module-deploy` using `fluent module install` instead. Module install deploys workflows, settings, and rules as a single atomic unit with proper versioning.
-
-**Use this skill only for standalone workflow uploads** — workflows not bundled in a module, hotfixes to individual workflows, or when module install is not applicable.
-
-| Scenario | Correct Approach |
-|----------|-----------------|
-| Workflow is in `resources/workflows/` of a module | `/fluent-module-deploy` → `fluent module install` |
-| Workflow changed along with Java rules | `/fluent-build` → `/fluent-module-deploy` (module bundles everything) |
-| Standalone workflow JSON not in any module | This skill (`/fluent-workflow-deploy`) |
-| Hotfix to a single workflow in production | This skill (targeted upload) |
-| Module install excluded workflows (`--exclude workflows`) | This skill (deploy workflows separately) |
-
-## When to Use
-
-- Uploading a standalone workflow definition not bundled in a module
-- Deploying after `fluent workflow merge` fails to upload (known `token:undefined` bug)
-- Deploying workflows excluded during module install (`--exclude workflows`)
-- Automating workflow deployment in CI/CD pipelines
-- Rolling back to a previous workflow version
-
-## Deployment Pipeline
-
-### Step 0: Verify CLI Available
-
-```bash
-fluent --version
-```
-
-If CLI is not found, warn the user. The CLI is needed for verification (workflow list/download) but not strictly required for upload -- the MCP `workflow.upload` tool and REST API work independently.
-
-### Step 1: Pre-flight Checks
-
-Before uploading, validate:
-
-1. **Read the workflow JSON file** -- confirm it parses as valid JSON
-2. **Verify required fields:** `name`, `retailerId`, `rulesets`, `statuses`
-3. **Query current deployed version:**
-   ```bash
-   fluent workflow list -p <profile> -r <retailer>
-   ```
-4. **Confirm new version > current version** (warn if same/lower)
-5. **Validate JSON structure** (use `/fluent-workflow-builder` validation checklist)
-6. **Check rule references** -- every rule in `rulesets[].rules[].name` should exist in `plugin.list`. If any are missing, **STOP** and advise deploying the module first.
-
-### Step 1.5: Check Pre-Deploy Report (if available)
-
-Read the pre-deploy checklist report if it exists:
-
-```
-accounts/<PROFILE>/analysis/pre-deploy/<MODULE>-<VERSION>.checklist.json
-```
-
-If found and `overallResult == "BLOCKED"`, warn the user and list the blocking gates. Do not proceed without explicit user confirmation.
-
-### Step 2: Upload (Strategy Selection)
-
-Try upload strategies in order:
-
-#### Strategy 1 (Primary): MCP `workflow.upload` Tool
-
-The `workflow.upload` MCP tool has built-in structure validation and supports dry-run mode:
-
-```
-workflow.upload({
-  workflow: <workflow-json-object>,
-  dryRun: true,     // Validate without deploying
-  validate: true    // Run structure checks
-})
-```
-
-1. First run with `dryRun: true` to validate
-2. If validation passes, run with `dryRun: false` to deploy
-3. Response includes the new version number
-
-**Advantages:** Built-in validation, dryRun mode, no manual auth handling.
-
-**When this fails:** MCP server not configured, connection issues, or MCP tool returns error.
-
-#### Strategy 2 (Fallback): REST API Direct Upload
-
-If MCP tool is unavailable, use the REST API directly:
-
-```bash
-# Extract credentials from CLI profile
-PROFILE_DIR="$HOME/.fluentcommerce/<profile>"
-BASE_URL=$(python3 -c "import json; print(json.load(open('$PROFILE_DIR/profile.json'))['baseUrl'])")
-CLIENT_SECRET=$(python3 -c "import json; print(json.load(open('$PROFILE_DIR/profile.json'))['clientSecret'])")
-ACCOUNT_ID=$(python3 -c "import json; print(json.load(open('$PROFILE_DIR/profile.json'))['id'])")
-
-# Get retailer credentials
-RETAILER_FILE="$PROFILE_DIR/retailer.<retailer-ref>.json"
-USERNAME=$(python3 -c "import json; d=json.load(open('$RETAILER_FILE')); print(d['defaultUser']['username'])")
-PASSWORD=$(python3 -c "import json; d=json.load(open('$RETAILER_FILE')); print(d['defaultUser']['password'])")
-
-# Authenticate (retailer-scoped token required -- account-level tokens return 403)
-TOKEN=$(curl -s -X POST "$BASE_URL/oauth/token" \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -d "username=$USERNAME&password=$PASSWORD&client_id=$ACCOUNT_ID&client_secret=$CLIENT_SECRET&grant_type=password&scope=api" \
-  | python3 -c "import sys,json; print(json.load(sys.stdin)['access_token'])")
-
-# Upload
-curl -s -X PUT "$BASE_URL/api/v4.1/workflow" \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "fluent.account: $ACCOUNT_ID" \
-  -d @<workflow-file>
-```
-
-**Success response:**
-```json
-{
-  "entityId": "2-ORDER::HD::1.51",
-  "eventStatus": "COMPLETE"
-}
-```
-
-**Error responses:**
-
-| HTTP Code | Cause | Fix |
-|-----------|-------|-----|
-| 401 | Token expired or invalid | Re-authenticate |
-| 403 | Account-level token, not retailer-scoped | Use retailer user credentials |
-| 400 | Invalid workflow JSON | Check structure with `/fluent-workflow-builder` |
-| 409 | Version conflict | Bump version number |
-| 500 | Server error | Retry after 5 seconds |
-
-#### Strategy 3 (Last Resort): CLI `fluent workflow merge`
-
-```bash
-fluent workflow merge <fragment-or-workflow> <workflow-name> \
-  -p <profile> -r <retailer>
-```
-
-Known issue: The CLI authenticates for the merge but not for the upload step, resulting in `token:undefined`. When this happens, the merged file is still written locally as `<filename>.merged.json`. Proceed to Strategy 2 with the merged file.
-
-### Step 3: Verify Deployment
-
-```bash
-fluent workflow list -p <profile> -r <retailer>
-```
-
-Confirm the version number matches the uploaded version.
-
-Additionally, download and diff to confirm content:
-
-```bash
-fluent workflow download -p <profile> -r <retailer> -w <name> -o /tmp/
-```
-
-Compare ruleset count and status count between uploaded and downloaded versions.
-
-### Step 4: Post-Deploy Validation (Optional)
-
-Send a test event to verify the workflow processes correctly:
-
-1. Find or create a test entity in a suitable status
-2. `event.build` -- preview the test event payload
-3. `event.send` (dryRun: true) -- validate without sending
-4. `event.send` (dryRun: false) -- send real event
-5. `event.list` -- confirm event processed (eventStatus: COMPLETE/SUCCESS)
-6. `graphql.query` -- verify entity status changed as expected
-
-Use `/fluent-e2e-test` for comprehensive post-deploy testing.
-
-## Module Dependency Check
-
-**Critical:** If the workflow references custom rules (rules with `<ACCOUNT>.<context>.<RuleName>` pattern rather than `FLUENTRETAIL.*`), verify the module containing those rules is deployed:
-
-```
-plugin.list({ name: "<RuleName>" })
-```
-
-If any referenced rule is not found in the registry, the module must be deployed first via `/fluent-module-deploy`. Deploying a workflow that references unregistered rules causes NO_MATCH events at runtime.
-
-**Recommended deployment order:**
-1. Deploy module (registers rules) -- `/fluent-module-deploy`
-2. Deploy workflows (references rules) -- `/fluent-workflow-deploy`
-3. Create/update settings (referenced by rules) -- `/fluent-settings`
-4. Run E2E test -- `/fluent-e2e-test`
-
-## Dry Run Mode
-
-With `--dry-run`, the deployer performs all steps except the actual upload:
-
-```
-1. Parse and validate workflow JSON         done
-2. Check current deployed version           done
-3. Verify version bump                      done
-4. Check rule references exist              done
-5. Upload workflow                          SKIPPED
-6. Report what WOULD be deployed
-```
-
-## Rollback
-
-To rollback to a previous version:
-
-1. Download the previous version:
-   ```bash
-   fluent workflow download -p <profile> -r <retailer> -w <name> -o /tmp/
-   ```
-
-2. Edit the downloaded JSON to bump the version number (must be higher than current)
-3. Upload via MCP tool or REST API
-
-Note: Fluent does not support downgrading version numbers. To "rollback," you upload the old content with a new (higher) version number.
-
-## Integration with Other Skills
-
-| Task | Skill |
-|------|-------|
-| Analyze workflow before deploying | `/fluent-workflow-analyzer` |
-| Edit workflow JSON | `/fluent-workflow-builder` |
-| Download current workflow | `/fluent-workflow` |
-| Deploy module (rules must exist first) | `/fluent-module-deploy` |
-| Pre-deployment validation | `/fluent-pre-deploy-check` |
-| Test after deployment | `/fluent-e2e-test` |
-| Debug deployment failures | `/fluent-trace` |
-
-## Tips
-
-- **Always backup the current version** before deploying -- download with `fluent workflow download`
-- **Version must always increase** -- Fluent rejects same or lower version numbers
-- **Use retailer-scoped tokens** for REST API -- Account-level tokens get 403 on workflow API
-- **Check the `eventStatus`** in the upload response -- `COMPLETE` means success
-- **The `entityId` in the response** follows format `<retailerId>-<workflowName>::<version>`
-- **Deploy module before workflow** if the workflow references new custom rules
-- **Windows users**: Use `--json` flag for download to avoid `::` filename issues