@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/dev/skills/fluent-settings/SKILL.md

@@ -10,8 +10,28 @@ argument-hint: [--audit <workflow-file>] [--context RETAILER|ACCOUNT|LOCATION] [
 
 Manage Fluent Commerce settings that configure how workflow rules behave at runtime. Settings are the critical glue between deployed workflows and working business logic — when a setting is missing, rules fail silently, orders get stuck, and webhooks never fire.
 
+## Pre-flight: Feedback Check
+
+Before starting, check for past learnings from this skill:
+
+1. Check if `accounts/<PROFILE>/feedback/fluent-settings.jsonl` exists
+2. If yes, read last 20 records
+3. Filter to: same entity type/subtype if known, FAILURE or USER_CORRECTED outcomes, confidence = CONFIRMED or PROMOTED
+4. Extract top 3 relevant learnings — use as internal "WATCH OUT" guidance during execution
+5. Do NOT show raw feedback to the user — silently adjust approach based on past issues
+
 ## 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 these settings, OR check `accounts/<PROFILE>/tasks/` for a task plan with `Status: APPROVED`
+2. **If multi-artifact work** (settings + 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 §9 (Settings) section
+4. **If settings-only work with no plan:** Continue to the Planning Gate below to write a plan for this skill
+5. **Read-only operations** (audit, discover, list) are always exempt from planning
+
 **Before creating or updating any settings, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** Every setting row must carry a Source column (NEW/EXISTING/MODIFIED). Read-only operations (audit, discover, list) are exempt.
 
 **Settings-specific emphasis — ensure these are covered:**
@@ -23,10 +43,29 @@ Manage Fluent Commerce settings that configure how workflow rules behave at runt
 5. **Impacted retailers (Section 4.8)** — settings take effect immediately; confirm target environment
 6. **Risks (Section 7)** — wrong values can break live flows; note immediate-effect risk
 
-**Write the plan to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-settings-<slug>.md`. Set `Status: PENDING`.
+**Write the plan to:** `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-settings-<slug>.md`. Set `Status: PENDING`.
 
 Present the full plan content to the user and wait for approval before sending any `setting.upsert` or `setting.bulkUpsert` calls. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
 
+## Handoff Protocol
+
+### Signals emitted by this skill
+
+| Signal | Condition | Example |
+|--------|-----------|---------|
+| `-> READY: <path>` | Settings applied | `-> READY: 3 settings upserted for retailer HM_TEST` |
+| `-> NEXT: /fluent-<skill>` | Next skill in plan | `-> NEXT: /fluent-e2e-test` |
+| `-> BLOCKED: <reason>` | Cannot proceed | `-> BLOCKED: ENV_UNREACHABLE — Cannot connect to Fluent environment` |
+| `-> SKIP: <reason>` | Read-only audit, no changes | `-> SKIP: Audit mode — no settings changes needed` |
+
+### Error codes
+
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| `PLAN_REQUIRED` | Settings creation attempted without approved plan | Run `/fluent-feature-plan` first |
+| `VALIDATION_FAILED` | Setting value format invalid or context missing | Fix setting values and retry |
+| `ENV_UNREACHABLE` | Cannot connect to Fluent environment | Check credentials via `config.validate` |
+
 ## Ownership Boundary
 
 This skill owns Settings CRUD, discovery, audit, and migration.
@@ -328,6 +367,9 @@ After extracting setting refs from the workflow:
 
 1. Query live setting values (`settings(... name: [...])`).
 2. Query orchestration audit for webhook actions on a target entity:
+
+   > **Event filter reference:** For complete filter syntax, see `/fluent-event-api`. The examples below show settings-specific patterns.
+
    ```
    event.list({
      "eventType": "ORCHESTRATION_AUDIT",
@@ -462,6 +504,64 @@ When invoked from `/fluent-connection-analysis`, use the webhook/setting depende
 5. Return combined audit report with Value Check column
 ```
 
+## Phase 2D: Settings Conflict Detection
+
+Before creating or updating settings, check for ownership conflicts across features.
+
+### What is a Conflict?
+
+A **settings conflict** occurs when:
+1. Two or more features declare the same setting key in their plans
+2. A setting being created already exists with a different value than expected
+3. Multiple feature plans reference the same setting key with different intended values
+
+### Detection Protocol
+
+**Step 1: Cross-feature scan**
+Scan all `accounts/<PROFILE>/features/*/plan.md` for settings tables (§9 Settings section). Extract all setting keys mentioned across all plans.
+
+**Step 2: Identify overlaps**
+If the same setting key appears in multiple feature plans:
+- Flag as `CONFLICT` if the planned values differ
+- Flag as `SHARED` if the planned values match (same value, multiple consumers — OK)
+- Flag as `OWNED` if only one plan references it
+
+**Step 3: Live environment check**
+Before `setting.upsert`, query the current value:
+```graphql
+{
+  settings(first: 1, name: ["<KEY>"], context: "<CONTEXT>") {
+    edges { node { id name value lobValue valueType contextId } }
+  }
+}
+```
+Compare existing value to planned value:
+- If no existing value → safe to create (`NEW`)
+- If existing value matches planned value → skip (`ALREADY_SET`)
+- If existing value differs from planned → flag as `OVERWRITE_WARNING`
+
+**Step 4: Present conflicts**
+```markdown
+### Settings Conflict Report
+
+| Key | Context | Feature A (planned) | Feature B (planned) | Live Value | Status |
+|-----|---------|--------------------|--------------------|------------|--------|
+| WEBHOOK_ENDPOINT_ORDER | RETAILER:5 | https://a.com/hook | https://b.com/hook | https://a.com/hook | CONFLICT |
+| ORDER_PREFIX | RETAILER:5 | HD- | HD- | HD- | SHARED |
+| NEW_SETTING | RETAILER:5 | value1 | — | (none) | OWNED |
+```
+
+**Step 5: Resolution**
+- `CONFLICT`: STOP. Present to user with both feature names. User must decide which value wins.
+- `OVERWRITE_WARNING`: WARN. Show current → new diff. User must confirm.
+- `SHARED` / `OWNED` / `NEW`: Proceed normally.
+
+### Handoff
+If conflicts are found:
+```
+-> BLOCKED: Settings conflict on <N> keys. User resolution required.
+```
+
 ## Phase 3: CRUD Operations
 
 ### Schema Reference (from live introspection)
@@ -1045,6 +1145,40 @@ Feed webhook payload reconstruction into the Phase 2 audit:
 | Debug rule failures caused by missing settings | `/fluent-trace` |
 | Query user actions that source options from settings | `/fluent-transition-api` |
 
+## 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.
+
+## Handoff
+
+| Output Artifact | Consumed By | Path |
+|----------------|-------------|------|
+| Settings created/updated in Fluent environment | `/fluent-pre-deploy-check` (Phase 5 validation) | Live environment via `graphql.query` |
+| Settings audit report | `/fluent-workflow-builder` (dependency check) | `accounts/<PROFILE>/analysis/settings/settings-audit.json` |
+
+## Error Reporting
+
+Errors from this skill follow the standard format:
+
+| Field | Description |
+|-------|-------------|
+| `phase` | Skill phase where error occurred (e.g., `audit`, `creation`, `update`, `migration`, `validation`) |
+| `severity` | `CRITICAL` (blocks downstream), `HIGH` (needs fix), `MEDIUM` (advisory), `LOW` (informational) |
+| `message` | Human-readable error description |
+| `resolution` | Suggested fix or downstream skill to invoke |
+
 ## Tips
 
 - **Settings names are case-sensitive** — `webhook.Order.Created` and `webhook.order.created` are different settings
@@ -1056,3 +1190,28 @@ Feed webhook payload reconstruction into the Phase 2 audit:
 - **Update requires 4 fields** — `id`, `valueType`, `context`, `contextId` are all required even if you only want to change the value. Omitting any will cause a validation error.
 - **Transition API `source` field** references settings — when `source: "settings.cancellationReasons"` appears in a user action attribute, that means a setting named `cancellationReasons` (or similar) must exist for the dropdown to populate.
 - **Always query before creating** during migration — creating a setting with a name that already exists at the same context may fail or create a duplicate depending on the Fluent version.
+
+## Post-Execution: Feedback Capture
+
+After completing this skill (whether success or failure), write a feedback record:
+
+1. **Classify outcome:** `SUCCESS` (settings applied), `PARTIAL_SUCCESS` (some settings failed), `FAILURE` (could not complete), `BLOCKED` (env unreachable), `USER_CORRECTED` (user overrode values/approach)
+2. **Build record:** Create a `feedback-record-v1` JSON object with:
+   - `skill`: `"fluent-settings"`
+   - `feature`: feature slug if applicable
+   - `entityType` / `entitySubtype`: entity type the settings configure (if applicable)
+   - `phases`: trace of each phase (pre-flight, plan, audit, upsert, verify) with PASS/FAIL/SKIP
+   - `learnings`: any gotchas discovered (wrong value type, missing context, silent failure)
+   - `userCorrections`: any corrections the user provided
+3. **Redact secrets:** Strip webhook URLs with tokens, API keys. Keep setting names and contexts.
+4. **Append** one JSON line to `accounts/<PROFILE>/feedback/fluent-settings.jsonl`
+5. **Update** `accounts/<PROFILE>/feedback/index.json` counters (create with `mkdir -p` if missing)
+
+**Skip capture if:** The execution was read-only (audit, discover, list — no mutations).
+
+## Known Pitfalls
+<!-- feedback-promoted: managed section, updated by feedback loop -->
+
+_(No promoted learnings yet.)_
+
+<!-- end feedback-promoted -->

package/content/dev/skills/fluent-source-onboard/SKILL.md

@@ -72,9 +72,11 @@ This skill does **not** own:
 
 ## Execution Protocol
 
-### Phase 1: Source Analysis
+**Phase ordering note:** Unlike most implementation skills, source-onboard runs analysis (Phase 1) BEFORE the planning gate (Phase 2). This is intentional — you must understand what exists before you can plan the restructuring. Phase 1 is read-only analysis. Phase 2 is the mandatory approval gate before any files are modified.
 
-**Goal:** Understand what exists, classify its state, and identify all rule classes.
+### Phase 1: Source Analysis (read-only)
+
+**Goal:** Understand what exists, classify its state, and identify all rule classes. **No files are modified in this phase.**
 
 #### Step 1.1: Classify Source Layout
 
@@ -150,9 +152,18 @@ plugin.list (compact: true)
 
 ### Phase 2: 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 onboarding, OR check `accounts/<PROFILE>/tasks/` for a task plan with `Status: APPROVED`
+2. **If multi-artifact work** (onboarding as part of larger feature): STOP. Invoke `/fluent-feature-plan` first
+3. **If approved plan found:** Skip to implementation, referencing the plan's relevant sections
+4. **If source-onboard-only work with no plan:** Continue to the Planning Gate below
+
 **MANDATORY: Present a restructuring plan before making ANY changes.** Use the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill as the base structure. Every table row must carry a Source column (NEW/EXISTING/MODIFIED/REUSED/OOTB). Extend with the source-onboard-specific sections below.
 
-Write the plan to: `accounts/<PROFILE>/plans/<YYYY-MM-DD>-source-onboard-<slug>.md`. Set `Status: PENDING`.
+Write the plan to: `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-source-onboard-<slug>.md`. Set `Status: PENDING`.
 
 **Source-onboard specific sections** (in addition to the standard template):
 
@@ -256,6 +267,23 @@ accounts/<PROFILE>/SOURCE/fluentcommerce-fc-module-<module-name>/
 
 **Wait for user approval.** On `--dry-run`, output the plan and exit without making changes.
 
+## Handoff Protocol
+
+### Signals emitted by this skill
+
+| Signal | Condition | Example |
+|--------|-----------|---------|
+| `-> READY: <path>` | Module restructured | `-> READY: accounts/HMDEV/SOURCE/fc-module-restructured/` |
+| `-> NEXT: /fluent-<skill>` | Ready for build + validation | `-> NEXT: /fluent-build` |
+| `-> BLOCKED: <reason>` | Cannot proceed | `-> BLOCKED: PREREQ_MISSING — No source code found at specified path` |
+
+### Error codes
+
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| `PREREQ_MISSING` | No source code found at the specified path | Provide correct path or clone repo |
+| `VALIDATION_FAILED` | Source cannot be restructured (incompatible format) | Manual intervention required |
+
 ### Phase 3: Execute Restructuring
 
 After approval, execute the plan in this order: