@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/dev/skills/fluent-session-summary/SKILL.md

@@ -1,195 +1,320 @@
----
-name: fluent-session-summary
-description: Track and summarize all code and Fluent environment changes made during a session. Maintains a running change log and produces a structured audit report (Text or JSON). Triggers on "session summary", "what did we change", "change summary", "show changes", "export audit".
-user-invocable: true
-allowed-tools: Bash, Read, Write
-argument-hint: [show|reset|export --json]
----
-
-# Session Change Tracking
-
-Track ALL changes made during a session — both code modifications and Fluent Commerce environment mutations — and produce a structured audit summary on demand.
-
-## Behaviour
-
-This is a **cross-cutting concern**, not a phase-specific skill. It applies alongside every other skill.
-
-### What to Track
-
-**Fluent environment changes (live account):**
-- GraphQL mutations executed (entity type, ref/id, fields changed)
-- Workflows deployed or uploaded (name, version, retailer)
-- Settings created or updated (key, context, value summary)
-- Events sent via `event.send` (name, entity type, entity ref, sync/async, outcome)
-- Modules deployed via CLI (name, version, retailer)
-- Batch jobs created and sent (job name, entity type, record count, outcome)
-- Entities created or updated (locations, networks, catalogues, carriers, users, orders, fulfilments, inventory positions, products, virtual catalogues, etc.)
-
-**Code changes (local workspace):**
-- Files created, modified, or deleted (path + brief description)
-- Workflow JSON edits (ruleset added/removed, trigger changed, state added)
-- Rule classes scaffolded or modified
-- Git commits made (hash, message, repo)
-- Git pushes (repo, branch, remote)
-
-**Read-only operations are NOT tracked** — queries, downloads, analysis, introspection, event listing, and diagnostics are informational and do not change state.
-
-### When to Present
-
-- When the user asks: "what did we change?", "summary", "show changes", "wrap up", or invokes `/fluent-session-summary`
-- Proactively before ending a session that involved significant changes (3+ write operations)
-- After completing a multi-step task (e.g., build-deploy-test cycle)
-
-### Text Summary Format (Default)
-
-```markdown
-## Session Change Summary
-
-**Profile:** <PROFILE> | **Account:** <account> | **Retailer:** <RETAILER_REF> (ID <N>)
-**Duration:** <first change time> - <last change time>
-
-### Environment Changes
-| # | Action | Type | Ref / Key | Details |
-|---|--------|------|-----------|---------|
-| 1 | Created | Setting | WEBHOOK_ORDER_URL | context=RETAILER:5, value=https://... |
-| 2 | Created | Order | HD_TEST_20260222_1 | type=HD, status=CREATED |
-| 3 | Sent Event | CreateOrder | ORDER/HD_TEST_20260222_1 | async, SUCCESS |
-| 4 | Mutation | Order | HD_TEST_20260222_1 | status CREATED -> BOOKED |
-| 5 | Deployed | Workflow | ORDER::HD | v12 -> retailer HM_TEST |
-| 6 | Deployed | Module | hm-extensions | v1.2.3 -> retailer HM_TEST |
-| 7 | Batch | Product | job-12345 | 50 records, COMPLETE |
-
-### Code Changes
-| # | Action | Path | Details |
-|---|--------|------|---------|
-| 1 | Modified | workflows/ORDER__HD.json | Added ruleset HandleCancellation |
-| 2 | Created | src/.../CancelOrderRule.java | New rule class + test |
-| 3 | Modified | resources/module.json | Registered CancelOrderRule |
-| 4 | Committed | fluent-mcp-extn | abc1234 - feat: add cancel support |
-| 5 | Pushed | fluent-mcp-extn | main -> origin/main |
-
-### Totals
-| Category | Count |
-|----------|-------|
-| GraphQL mutations | N |
-| Events sent | N |
-| Settings changed | N |
-| Workflows deployed | N |
-| Modules deployed | N |
-| Batch jobs | N |
-| Files modified | N |
-| Git commits | N |
-
-### Irreversible Actions
-> List any destructive or hard-to-reverse changes here (entity deletions, workflow version overwrites, forced re-deploys). Flag prominently so the user is aware.
-```
-
-### JSON Export Format (`export --json`)
-
-> **For compliance-grade exports** with traceability matrices, rollback commands, and external system mapping, use `/fluent-session-audit-export`. This quick JSON export is a lightweight alternative for simple session records.
-
-When the user asks to "export audit" or runs with `export --json`, generate a JSON file (e.g., `session-audit-<TIMESTAMP>.json`) with this structure:
-
-<!-- Validate Mermaid blocks per /fluent-mermaid-validate rules -->
-```mermaid
-classDiagram
-    class SessionAudit {
-        String session_id
-        String timestamp
-        Target target
-        Changes changes
-        String summary
-    }
-    class Target {
-        String profile
-        String retailer
-        String account
-    }
-    class Changes {
-        CodeChange[] code
-        EnvChange[] environment
-    }
-    class CodeChange {
-        String timestamp
-        String action
-        String file
-        String description
-    }
-    class EnvChange {
-        String timestamp
-        String action
-        String type
-        String ref
-        String details
-        String outcome
-    }
-    
-    SessionAudit *-- Target
-    SessionAudit *-- Changes
-    Changes *-- CodeChange
-    Changes *-- EnvChange
-```
-
-```json
-{
-  "session_id": "UUID",
-  "timestamp": "ISO-8601",
-  "target": {
-    "profile": "PROFILE_NAME",
-    "retailer": "RETAILER_REF",
-    "account": "ACCOUNT_NAME"
-  },
-  "changes": {
-    "code": [
-      { "timestamp": "ISO", "action": "modified", "file": "path/to/file", "description": "Added ruleset" },
-      { "timestamp": "ISO", "action": "created", "file": "path/to/file", "description": "New rule class" }
-    ],
-    "environment": [
-      { "timestamp": "ISO", "action": "mutation", "type": "ORDER", "ref": "ORD-123", "details": "status -> BOOKED" },
-      { "timestamp": "ISO", "action": "event", "name": "ConfirmPick", "entity": "FULFILMENT", "ref": "FUL-123", "outcome": "SUCCESS" }
-    ]
-  },
-  "summary": "Brief text summary of the session goals and outcomes."
-}
-```
-
-### Tracking Protocol
-
-1. **As changes happen:** After each write operation (mutation, event send, deploy, file edit, commit), mentally append it to the running log. Do not wait until the end to reconstruct.
-2. **On `/fluent-session-summary show`:** Present the full text table.
-3. **On `/fluent-session-summary export --json`:** Write the JSON artifact to the workspace root.
-4. **On `/fluent-session-summary reset`:** Clear the running log (start fresh, e.g., when switching accounts mid-session).
-5. **Group by account/retailer** if the session spans multiple profiles or retailers.
-6. **Include outcome** where known (SUCCESS, FAILED, NO_MATCH) — especially for events.
-7. **For mutations**, note the key fields changed rather than full payloads.
-8. **For workflow deploys**, note the version number deployed.
-
-### Integration with Other Skills
-
-Every skill that performs write operations should contribute to this log:
-
-| Skill | Tracked actions |
-|-------|----------------|
-| `fluent-workflow-builder` | Workflow JSON edits (local file changes) |
-| `fluent-build` | Version bumps, module packaging |
-| `fluent-module-deploy` | Module installs to retailers |
-| `fluent-workflow-deploy` | Workflow uploads to retailers |
-| `fluent-settings` | Setting create/update mutations |
-| `fluent-retailer-config` | Entity creation (locations, networks, catalogues, etc.) |
-| `fluent-test-data` | Test entity creation |
-| `fluent-e2e-test` | Events sent, entities created during test |
-| `fluent-rule-scaffold` | New Java classes and module.json changes |
-| `fluent-job-batch` | Batch job creation, record sends |
-| `fluent-trace` | Events sent during diagnostic re-fires |
-| `fluent-custom-code` | Source code edits |
-| `fluent-module-scaffold` | Module skeleton creation |
-| `fluent-version-manage` | Version bumps, CHANGELOG updates, git tags |
-| `fluent-pre-deploy-check` | Pre-deploy gate results |
-| `fluent-session-audit-export` | Consumes same tracking data for compliance JSON |
-
-### Edge Cases
-
-- **Dry runs:** `event.send` with `dryRun: true` and `graphql.introspect` are NOT tracked (no state change).
-- **Failed writes:** Track with outcome=FAILED so the user knows what was attempted.
-- **Multi-retailer sessions:** Group changes under separate retailer headers.
-- **No changes made:** Report "No environment or code changes were made in this session."
+---
+name: fluent-session-summary
+description: Track and summarize all code and Fluent environment changes made during a session. Maintains a running change log and produces a structured audit report (Text or JSON). Triggers on "session summary", "what did we change", "change summary", "show changes", "export audit".
+user-invocable: true
+allowed-tools: Bash, Read, Write
+argument-hint: [show|reset|export --json]
+---
+
+# Session Change Tracking
+
+Track ALL changes made during a session — both code modifications and Fluent Commerce environment mutations — and produce a structured audit summary on demand.
+
+## Tracking Protocol Ownership
+
+This skill owns the session change tracking log format and protocol. The log is the single source of truth for all session changes.
+
+`/fluent-session-audit-export` consumes this log to produce compliance-grade JSON exports. Both skills MUST use the same log entries — there is no separate tracking mechanism. Changes are recorded once by this skill's protocol; the audit-export skill reads them.
+
+If extending the tracking format (new change types, new fields), update this skill first, then update `/fluent-session-audit-export` to consume the new format.
+
+## Behaviour
+
+This is a **cross-cutting concern**, not a phase-specific skill. It applies alongside every other skill.
+
+### Tracking Log Ownership
+
+This skill (`/fluent-session-summary`) **owns the tracking protocol** — it defines what to track, when to present, and the output format. All other skills that perform write operations contribute entries to this log as they execute.
+
+`/fluent-session-audit-export` **consumes the same tracking data** to produce compliance-grade JSON exports with traceability matrices and rollback commands. It does not maintain a separate tracking log — both skills share the same running session log.
+
+### What to Track
+
+**Fluent environment changes (live account):**
+- GraphQL mutations executed (entity type, ref/id, fields changed)
+- Workflows deployed or uploaded (name, version, retailer)
+- Settings created or updated (key, context, value summary)
+- Events sent via `event.send` (name, entity type, entity ref, sync/async, outcome)
+- Modules deployed via CLI (name, version, retailer)
+- Batch jobs created and sent (job name, entity type, record count, outcome)
+- Entities created or updated (locations, networks, catalogues, carriers, users, orders, fulfilments, inventory positions, products, virtual catalogues, etc.)
+
+**Code changes (local workspace):**
+- Files created, modified, or deleted (path + brief description)
+- Workflow JSON edits (ruleset added/removed, trigger changed, state added)
+- Rule classes scaffolded or modified
+- Git commits made (hash, message, repo)
+- Git pushes (repo, branch, remote)
+
+**Skill invocations (agent decision trail):**
+- Skill name invoked (e.g., `/fluent-rule-scaffold`, `/fluent-build`)
+- Invocation timestamp
+- Key arguments passed (profile, retailer, entity type, module name — NOT full file contents)
+- Outcome: `completed` | `failed` | `skipped` (with reason)
+- Downstream skill recommended (from Handoff section, if any)
+
+**MCP tool calls (API-level operations):**
+- Tool name (e.g., `event.send`, `graphql.query`, `entity.create`, `workflow.upload`)
+- Entity type and ref targeted
+- Outcome: `ok: true/false`
+- Whether it was a read (query/list/get) or write (mutation/send/create/update/deploy)
+- Read-only tool calls are tracked when `--include-readonly` is specified; write tool calls are always tracked
+
+**Decision trail (why the agent chose a path):**
+- Decision timestamp + step id
+- Trigger (user request, workflow gate, error recovery, or handoff)
+- Options considered (2-4 short labels)
+- Selected option + rationale
+- Confidence (`high` | `medium` | `low`) and assumptions list
+
+**Read-only operations are NOT tracked as state changes** — queries, downloads, analysis, introspection, event listing, and diagnostics do not appear in Environment/Code change counts. They can still be listed under `MCP Tool Calls` when `--include-readonly` is enabled.
+
+### When to Present
+
+- When the user asks: "what did we change?", "summary", "show changes", "wrap up", or invokes `/fluent-session-summary`
+- Proactively before ending a session that involved significant changes (3+ write operations)
+- After completing a multi-step task (e.g., build-deploy-test cycle)
+
+### Text Summary Format (Default)
+
+```markdown
+## Session Change Summary
+
+**Profile:** <PROFILE> | **Account:** <account> | **Retailer:** <RETAILER_REF> (ID <N>)
+**Duration:** <first change time> - <last change time>
+
+### Environment Changes
+| # | Action | Type | Ref / Key | Details |
+|---|--------|------|-----------|---------|
+| 1 | Created | Setting | <SETTING_KEY_1> | context=RETAILER:<RETAILER_ID>, value=https://... |
+| 2 | Created | Order | <ORDER_REF_1> | type=<ORDER_SUBTYPE>, status=CREATED |
+| 3 | Sent Event | <EVENT_NAME_1> | <ENTITY_TYPE>/<ORDER_REF_1> | async, SUCCESS |
+| 4 | Mutation | Order | <ORDER_REF_1> | status <STATUS_FROM> -> <STATUS_TO> |
+| 5 | Deployed | Workflow | <WORKFLOW_NAME> | v<WORKFLOW_VERSION> -> retailer <RETAILER_REF> |
+| 6 | Deployed | Module | <MODULE_NAME> | v<VERSION> -> retailer <RETAILER_REF> |
+| 7 | Batch | Product | <BATCH_JOB_ID> | <RECORD_COUNT> records, COMPLETE |
+
+### Code Changes
+| # | Action | Path | Details |
+|---|--------|------|---------|
+| 1 | Modified | workflows/<WORKFLOW_FILE>.json | Added ruleset <RULESET_NAME> |
+| 2 | Created | src/.../<RULE_CLASS>.java | New rule class + test |
+| 3 | Modified | resources/module.json | Registered <RULE_CLASS> |
+| 4 | Committed | <REPO_NAME> | <COMMIT_HASH> - feat: <FEATURE_DESCRIPTION> |
+| 5 | Pushed | <REPO_NAME> | <BRANCH_NAME> -> <REMOTE_NAME>/<BRANCH_NAME> |
+
+### Skill Invocations
+| # | Timestamp | Skill | Arguments | Outcome | Next |
+|---|-----------|-------|-----------|---------|------|
+| 1 | 09:00 | /fluent-rule-scaffold | <RULE_CLASS>, <ENTITY_TYPE> | completed | /fluent-build |
+| 2 | 09:45 | /fluent-build | <MODULE_NAME> | completed | /fluent-pre-deploy-check |
+| 3 | 10:00 | /fluent-pre-deploy-check | <MODULE_NAME> <VERSION> | completed (READY) | /fluent-module-deploy |
+
+### Decision Trail
+| # | Timestamp | Trigger | Options | Selected | Rationale | Confidence |
+|---|-----------|---------|---------|----------|-----------|------------|
+| 1 | 08:58 | User asks for deployment readiness | Build only, Build+Checklist | Build+Checklist | Prevent unsafe deploy without gate evidence | high |
+| 2 | 09:10 | Workflow mismatch detected | Re-download workflow, Patch in place | Re-download workflow | Avoid patching stale baseline | high |
+| 3 | 09:40 | Build failure on missing setting | Retry build, Fix setting first | Fix setting first | Root cause is config, retry would fail again | medium |
+
+### MCP Tool Calls
+| # | Timestamp | Tool | Target | Write? | Outcome |
+|---|-----------|------|--------|--------|---------|
+| 1 | 09:12 | setting.upsert | <SETTING_KEY_2> | Yes | ok |
+| 2 | 10:02 | workflow.upload | <WORKFLOW_NAME> | Yes | ok |
+| 3 | 10:15 | event.send | <ENTITY_TYPE>/<ENTITY_REF_1> | Yes | ok |
+
+### Totals
+| Category | Count |
+|----------|-------|
+| GraphQL mutations | N |
+| Events sent | N |
+| Settings changed | N |
+| Workflows deployed | N |
+| Modules deployed | N |
+| Batch jobs | N |
+| Files modified | N |
+| Git commits | N |
+| Skills invoked | N |
+| MCP tool calls (write) | N |
+| Decision trail entries | N |
+
+### Irreversible Actions
+> List any destructive or hard-to-reverse changes here (entity deletions, workflow version overwrites, forced re-deploys). Flag prominently so the user is aware.
+```
+
+### JSON Export Format (`export --json`)
+
+> **For compliance-grade exports** with traceability matrices, rollback commands, and external system mapping, use `/fluent-session-audit-export`. This quick JSON export is a lightweight alternative for simple session records.
+
+When the user asks to "export audit" or runs with `export --json`, generate a JSON file (e.g., `session-audit-<TIMESTAMP>.json`) with this structure:
+
+<!-- Validate Mermaid blocks per /fluent-mermaid-validate rules -->
+```mermaid
+classDiagram
+    class SessionAudit {
+        String session_id
+        String timestamp
+        Target target
+        Changes changes
+        String summary
+    }
+    class Target {
+        String profile
+        String retailer
+        String account
+    }
+    class Changes {
+        CodeChange[] code
+        EnvChange[] environment
+    }
+    class CodeChange {
+        String timestamp
+        String action
+        String file
+        String description
+    }
+    class EnvChange {
+        String timestamp
+        String action
+        String type
+        String ref
+        String details
+        String outcome
+    }
+    
+    SessionAudit *-- Target
+    SessionAudit *-- Changes
+    Changes *-- CodeChange
+    Changes *-- EnvChange
+```
+
+```json
+{
+  "session_id": "UUID",
+  "timestamp": "ISO-8601",
+  "target": {
+    "profile": "PROFILE_NAME",
+    "retailer": "RETAILER_REF",
+    "account": "ACCOUNT_NAME"
+  },
+  "changes": {
+    "code": [
+      { "timestamp": "ISO", "action": "modified", "file": "path/to/file", "description": "Added ruleset" },
+      { "timestamp": "ISO", "action": "created", "file": "path/to/file", "description": "New rule class" }
+    ],
+    "environment": [
+      { "timestamp": "ISO", "action": "mutation", "type": "ORDER", "ref": "ORD-123", "details": "status -> BOOKED" },
+      { "timestamp": "ISO", "action": "event", "name": "ConfirmPick", "entity": "FULFILMENT", "ref": "FUL-123", "outcome": "SUCCESS" }
+    ],
+    "skillInvocations": [
+      { "timestamp": "ISO", "skill": "/fluent-build", "args": { "profile": "<PROFILE>" }, "outcome": "completed", "next": "/fluent-pre-deploy-check" }
+    ],
+    "toolCalls": [
+      { "timestamp": "ISO", "tool": "event.send", "target": "ORDER/ORD-123", "write": true, "outcome": "ok" }
+    ],
+    "decisionTrail": [
+      {
+        "timestamp": "ISO",
+        "trigger": "Build failed",
+        "options": ["retry", "fix-setting", "rollback"],
+        "selected": "fix-setting",
+        "rationale": "Missing setting is deterministic root cause",
+        "confidence": "high",
+        "assumptions": []
+      }
+    ]
+  },
+  "summary": "Brief text summary of the session goals and outcomes."
+}
+```
+
+### Tracking Protocol
+
+1. **At skill entry:** Append a `skillInvocation.start` record with skill name + sanitized arguments.
+2. **As tool calls execute:** Append `toolCall` records (write always, read only when `--include-readonly` is enabled).
+3. **At decision points:** Append `decisionTrail` records whenever the agent chooses between multiple valid paths (e.g., retry vs fix root cause, direct deploy vs pre-deploy check).
+4. **On write operations:** Append state changes (mutation, event send, deploy, file edit, commit) immediately. Do not reconstruct later.
+5. **At skill exit:** Mark invocation outcome (`completed`/`failed`/`skipped`) and recommended next skill.
+6. **On `/fluent-session-summary show`:** Present the full text table.
+7. **On `/fluent-session-summary export --json`:** Write the JSON artifact to the workspace root.
+8. **On `/fluent-session-summary reset`:** Clear the running log (start fresh, e.g., when switching accounts mid-session).
+9. **Group by account/retailer** if the session spans multiple profiles or retailers.
+10. **Include outcome** where known (SUCCESS, FAILED, NO_MATCH) — especially for events.
+11. **For mutations**, note the key fields changed rather than full payloads.
+12. **For workflow deploys**, note the version number deployed.
+
+### Integration with Other Skills
+
+Every skill that performs write operations should contribute to this log:
+
+| Skill | Tracked actions |
+|-------|----------------|
+| `fluent-workflow-builder` | Workflow JSON edits (local file changes) |
+| `fluent-build` | Version bumps, module packaging |
+| `fluent-module-deploy` | Module installs to retailers |
+| `fluent-workflow-deploy` | Workflow uploads to retailers |
+| `fluent-settings` | Setting create/update mutations |
+| `fluent-retailer-config` | Entity creation (locations, networks, catalogues, etc.) |
+| `fluent-test-data` | Test entity creation |
+| `fluent-e2e-test` | Events sent, entities created during test |
+| `fluent-rule-scaffold` | New Java classes and module.json changes |
+| `fluent-job-batch` | Batch job creation, record sends |
+| `fluent-trace` | Events sent during diagnostic re-fires |
+| `fluent-custom-code` | Source code edits |
+| `fluent-module-scaffold` | Module skeleton creation |
+| `fluent-version-manage` | Version bumps, CHANGELOG updates, git tags |
+| `fluent-pre-deploy-check` | Pre-deploy gate results |
+| `fluent-session-audit-export` | Consumes same tracking data for compliance JSON |
+| `fluent-archive` | Archives features — status transitions tracked |
+| `fluent-rollback` | Rollback operations tracked as changes |
+| `fluent-feature-status` | Complementary — feature lifecycle vs session changes |
+
+### Centralized Instrumentation Contract
+
+All skills should emit tracking records through one shared capture path:
+
+```
+track.skillStart(skillName, argsSanitized)
+track.toolCall(toolName, target, write, outcome, readonly)
+track.decision(trigger, options, selected, rationale, confidence, assumptions)
+track.change(category, action, target, details, reversible, outcome)
+track.skillEnd(skillName, outcome, nextSkill)
+```
+
+Rules:
+- Do not duplicate logs in each skill; use the shared tracker.
+- Keep arguments and payloads sanitized (no secrets, no large blobs).
+- Preserve chronological order across all categories.
+- Session summary and session audit export must read from this exact shared log.
+
+### Skill Handoff Convention
+
+All implementation skills should end their output with a structured "Recommended Next Steps" table to enable consistent agent-driven sequencing:
+
+| Priority | Skill | Reason |
+|----------|-------|--------|
+| 1 | `/fluent-workflow-analyzer` | Validate modified workflow |
+| 2 | `/fluent-pre-deploy-check` | Run pre-deployment validation |
+
+This convention replaces ad-hoc prose recommendations with a machine-scannable format.
+
+### Error Reporting Convention
+
+Skills should report errors using a consistent table format:
+
+| Severity | Code | Message | Skill | Remediation |
+|----------|------|---------|-------|-------------|
+| CRITICAL | DEPLOY_BLOCKED | Pre-deploy check failed | /fluent-module-deploy | Run /fluent-pre-deploy-check |
+| HIGH | BUILD_FAILED | Maven compilation error | /fluent-build | Fix compilation errors |
+| MEDIUM | SETTINGS_MISSING | Required setting not found | /fluent-settings | Create missing setting |
+
+### Edge Cases
+
+- **Dry runs:** `event.send` with `dryRun: true` and `graphql.introspect` are NOT tracked (no state change).
+- **Failed writes:** Track with outcome=FAILED so the user knows what was attempted.
+- **Multi-retailer sessions:** Group changes under separate retailer headers.
+- **No changes made:** Report "No environment or code changes were made in this session."
+- **Skill invocations with no changes:** A skill like `/fluent-workflow-analyzer` may be invoked but produce no tracked changes (read-only). It still appears in the Skill Invocations table but contributes 0 to change counts.
+- **MCP tool dryRun calls:** Tool calls with `dryRun: true` (e.g., `event.send`, `graphql.batchMutate`) are NOT tracked as writes. They appear in tool calls only if `--include-readonly` is specified.
+- **No explicit branching decision occurred:** Do not force decision records. `decisionTrail` can be empty.