@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/cli/skills/fluent-module-deploy/SKILL.md

@@ -12,6 +12,15 @@ Deploy modules to Fluent Commerce environments with validation and verification.
 
 ## 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 deployment, OR check `accounts/<PROFILE>/tasks/` for a task plan with `Status: APPROVED`
+2. **If multi-artifact work** (deploy + rules + workflows + settings): 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 §17 (Deployment) section
+4. **If deploy-only work with no plan:** Continue to the Planning Gate below to write a plan for this skill
+
 **Before deploying any module, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.**
 
 **Module-deploy specific emphasis — ensure these are covered:**
@@ -25,10 +34,41 @@ Deploy modules to Fluent Commerce environments with validation and verification.
 7. **Deployment Sequence (Section 9)** — pre-checks (validation, build, tests) → deploy → verify
 8. **Rollback Plan (Section 10)** — previous module version to restore if deployment fails
 
-**Write the plan to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-module-deploy-<slug>.md`. Set `Status: PENDING`.
+**Write the plan to:** `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-module-deploy-<slug>.md`. Set `Status: PENDING`.
 
 Present the full plan content to the user and wait for approval before running `fluent module install`. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
 
+## Pre-Flight: Pre-Deploy Check Gate
+
+**This gate is MANDATORY. Do not skip.**
+
+1. Search `accounts/<PROFILE>/reports/pre-deploy/` for `<MODULE>-<VERSION>.checklist.json`.
+2. **If found and `overallResult == "BLOCKED"`**: **STOP. Do NOT proceed.** List all blocking gates from the report. Require explicit user override ("deploy anyway") to continue past a BLOCKED verdict.
+3. **If found and `overallResult == "READY"`**: Proceed — pre-deploy validation passed.
+4. **If no report found**: WARN the user: "No pre-deploy-check report found for this module version. Run `/fluent-pre-deploy-check` first for comprehensive validation." Only proceed after explicit user confirmation ("deploy without validation").
+
+> **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>` | Module installed successfully | `-> READY: Module hm-extensions v0.0.30 installed to HM_TEST (retailer 5)` |
+| `-> NEXT: /fluent-<skill>` | Ready for workflow deploy or E2E test | `-> NEXT: /fluent-workflow-deploy` |
+| `-> BLOCKED: <reason>` | Deployment blocked | `-> BLOCKED: DEPLOYMENT_BLOCKED — Pre-deploy check verdict is BLOCKED` |
+| `-> SKIP: <reason>` | Module already at target version | `-> SKIP: Module already at v0.0.30 on retailer HM_TEST` |
+
+### Error codes
+
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| `PLAN_REQUIRED` | Deployment attempted without approved plan | Run `/fluent-feature-plan` first |
+| `DEPLOYMENT_BLOCKED` | Pre-deploy check report is BLOCKED | Run `/fluent-pre-deploy-check` and resolve gates |
+| `PREREQ_MISSING` | No pre-deploy report found | Run `/fluent-pre-deploy-check` first |
+| `ENV_UNREACHABLE` | Cannot connect to Fluent environment | Check credentials via `config.validate` |
+
 ## When to Use
 
 - Deploying reference modules from Fluent repository
@@ -42,7 +82,7 @@ Present the full plan content to the user and wait for approval before running `
 - [ ] Module source available (name, URL, or local path)
 - [ ] Dependencies installed
 - [ ] Configuration values ready (if module requires config)
-- [ ] Module validation passed (check `accounts/<PROFILE>/analysis/module-validate/<name>.report.json` — `summary.status` should be `READY_FOR_BUILD`). Run `/fluent-module-validate` if report is missing or stale.
+- [ ] Module validation passed (check `accounts/<PROFILE>/reports/module-validate/<name>.report.json` — `summary.status` should be `READY_FOR_BUILD`). Run `/fluent-module-validate` if report is missing or stale.
 
 ## Cross-Platform Command Notes
 
@@ -99,7 +139,7 @@ For local module paths (extension or data modules), run structural validation be
 
 **1. Check validation report:**
 
-Read `accounts/<PROFILE>/analysis/module-validate/<module-name>.report.json` if it exists.
+Read `accounts/<PROFILE>/reports/module-validate/<module-name>.report.json` if it exists.
 
 - If `summary.status == "READY_FOR_BUILD"` -- proceed
 - If `summary.status == "NEEDS_FIXES"` -- **STOP**. List the FAIL items from the report. Run `/fluent-module-validate` to refresh if the report is stale.
@@ -124,15 +164,17 @@ fluent module describe <module-name>
 - Read `<module-path>/resources/module.json` directly and confirm it parses as JSON.
 - Confirm the module type matches expectations (extension has `plugins/`, data has `resources/assets/`).
 
-### Step 3: Check Dependencies
+### Step 3: Check Dependencies (Mandatory Pre-flight)
 
 ```bash
-# List installed modules
+# List installed modules — MUST run before any install
 fluent module list -p <profile-name>
 
 # Compare with module.json dependencies
 ```
 
+**FAIL FAST:** If dependencies are missing, STOP immediately. Do not attempt to install the module — it will fail mid-operation. Install dependencies in the correct order first (see dependency order table above).
+
 If dependencies missing: install them first!
 
 **For reference modules**, enforce the dependency order:
@@ -331,6 +373,22 @@ After deploying a module that includes new custom rules, workflows referencing t
 
 **Deployment order:** Module (registers rules) -> Workflows (reference rules) -> Settings (referenced by rules) -> E2E test
 
+## Session Tracking
+
+When invoked, log the following to the session tracking protocol (consumed by `/fluent-session-summary` and `/fluent-session-audit-export`):
+
+**On entry:**
+```json
+{ "skill": "<this-skill-name>", "timestamp": "<ISO-8601>", "arguments": { "<key>": "<value>", "...": "..." } }
+```
+
+**On exit:**
+```json
+{ "skill": "<this-skill-name>", "outcome": "<completed|failed|skipped>", "changesProduced": ["<seq-numbers>"], "toolCallsProduced": ["<seq-numbers>"], "nextRecommended": "<from-handoff-section>" }
+```
+
+All MCP tool calls made during execution should include `"skill": "<this-skill-name>"` in their tracking record for attribution. The `arguments` object should capture the key parameters actually passed (profile, retailer, entity type, etc.) — not a fixed schema. The `nextRecommended` value comes from the Handoff section below.
+
 ## Best Practices
 
 1. **Always verify active profile** before installing

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

@@ -10,6 +10,8 @@ argument-hint: <operation> [profile-name]
 
 Manage Fluent CLI profiles for connecting to Fluent Commerce accounts.
 
+> **New to Fluent CLI?** Start with `/fluent-cli-index` for a complete command reference and routing guide.
+
 ## When to Use
 
 - Creating new connection to Fluent account
@@ -178,3 +180,74 @@ Profiles stored in: `~/.fluentcommerce/<profile-name>/`
 3. **Environment-specific profiles** - Don't mix dev/prod
 4. **Handle exports carefully** - Postman files contain plain-text credentials
 5. **Rotate credentials regularly** - Update profiles with new passwords
+
+## Credential Rotation
+
+To rotate credentials for a Fluent profile:
+
+1. Generate new credentials in Fluent Commerce admin console
+2. Update profile: `fluent profile update -n <PROFILE> --client-id <NEW_ID> --client-secret <NEW_SECRET>`
+3. Validate new credentials: `fluent profile test -n <PROFILE>` (or attempt `fluent workflow list -p <PROFILE>`)
+4. If validation succeeds, the rotation is complete
+5. If validation fails, revert: `fluent profile update -n <PROFILE> --client-id <OLD_ID> --client-secret <OLD_SECRET>`
+
+**Warning:** Never rotate credentials mid-deployment. Complete all in-flight deployments first.
+
+### Extended Rotation Procedure
+
+When credentials expire or are rotated by an admin, follow these steps:
+
+#### Step 1: Identify affected profiles
+
+```bash
+fluent profile list
+```
+
+Note which profiles use the rotated credentials (check username in each `~/.fluentcommerce/<PROFILE>/profile.json`).
+
+#### Step 2: Update profile credentials
+
+```bash
+fluent profile update <profile-name> \
+  --username <username> \
+  --password <new-password>
+```
+
+If the client secret was rotated:
+```bash
+fluent profile update <profile-name> \
+  --client-secret <new-client-secret>
+```
+
+#### Step 3: Update retailer user credentials (if applicable)
+
+```bash
+fluent profile update <profile-name> \
+  --retailer <retailer-ref> \
+  --username <retailer-admin> \
+  --password <new-password>
+```
+
+#### Step 4: Verify updated credentials
+
+```bash
+fluent profile use <profile-name>
+fluent profile active
+```
+
+If MCP servers are configured, restart them after updating credentials so they pick up the new profile data.
+
+#### Step 5: Verify MCP connectivity (if applicable)
+
+After restarting MCP servers, run `connection.test` to confirm authentication works with the new credentials.
+
+### Common rotation triggers
+
+| Trigger | What to update |
+|---------|---------------|
+| Password expired | `--password` on profile and retailer users |
+| Client secret rotated | `--client-secret` on profile |
+| User deactivated/replaced | `--username` + `--password` on profile |
+| Environment migration | Create new profile with new credentials |
+
+For a complete CLI command reference, see `/fluent-cli-index`.