@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/dev/skills/fluent-workspace-tree/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: fluent-workspace-tree
+description: Read-only visualization of the workspace directory structure with annotations, artifact counts, and feature status overlays.
+user-invocable: true
+allowed-tools: Bash, Read, Glob, Grep
+argument-hint: [--profile PROFILE] [--section source|workflows|features|reports|analysis|tasks|sessions] [--depth N]
+---
+
+# Workspace Tree Visualization
+
+Render an annotated directory tree of the workspace showing where everything lives, what each directory contains, and how many artifacts exist in each category. This is a **read-only** skill -- it writes no files and makes no mutations.
+
+## Ownership Boundary
+
+This skill owns: workspace directory structure visualization, artifact counting, file-level annotations, section filtering, depth control.
+
+Other skills own: feature lifecycle details (`/fluent-feature-status`), session changes (`/fluent-session-summary`), source code analysis (`/fluent-custom-code`), workflow structure analysis (`/fluent-workflow-analyzer`).
+
+**Delineation with `/fluent-feature-status --tree`:** This skill provides a structure-focused view with file-level annotations, section filtering, and depth control. `/fluent-feature-status --tree` provides a lifecycle-focused view with status priority sorting, attention flags, and next-action recommendations. Use this skill for "where is everything?"; use feature-status for "what should I work on next?"
+
+## Purpose
+
+Provide a visual map of the entire workspace organized by the three-axis layout (Feature, Module, Account). Help users understand where artifacts live, find specific files, and grasp the workspace structure at a glance.
+
+## When to Use
+
+- **Onboarding:** First time working with a workspace -- understand the layout before diving in.
+- **Finding artifacts:** "Where are the workflows?" "Where did that build report go?"
+- **Understanding workspace layout:** See the relationship between source code, workflows, features, and reports.
+- **Session start:** Quick orientation alongside `/fluent-feature-status` for a complete picture.
+- **After scaffolding:** Verify that new directories and files were created in the right places.
+
+## No Planning Gate
+
+This is a **read-only** diagnostic skill. No planning gate required. It can be invoked at any time without approval, writes no files, and makes no mutations.
+
+## Invocation
+
+```
+/fluent-workspace-tree
+/fluent-workspace-tree --profile SAGIRISH
+/fluent-workspace-tree --section features
+/fluent-workspace-tree --section source
+/fluent-workspace-tree --depth 2
+```
+
+## How It Works
+
+### Step 1: Discover Profiles
+
+Scan `accounts/` for profile directories:
+
+```
+accounts/*/
+```
+
+If `--profile <PROFILE>` is specified, show only that profile. If no profiles exist, report:
+
+```
+No accounts/ directory found. Run /fluent-bootstrap to set up your first profile.
+```
+
+### Step 2: Scan Directory Structure
+
+For each profile, scan and count artifacts in each category:
+
+**SOURCE (plugin repositories):**
+- Glob `accounts/<PROFILE>/SOURCE/*/` for repository directories
+- Identify each repo by the presence of `pom.xml` or `module.json`
+- Count: number of plugin repos
+
+**Workflows (retailer-scoped):**
+- Glob `accounts/<PROFILE>/workflows/*/` for retailer directories
+- Within each retailer dir, count `.json` files (excluding `workflow-context.json`)
+- Note the retailer ref from directory name
+
+**Features (lifecycle-managed):**
+- Glob `accounts/<PROFILE>/features/*/status.json`
+- Parse each `status.json` to get feature name and status
+- Count by status: N APPROVED, N PLANNING, etc.
+
+**Reports (ephemeral outputs):**
+- Check for subdirectories: `build/`, `pre-deploy/`, `module-validate/`, `e2e-test/`
+- Count files in each subdirectory
+- Note: these are ephemeral and replaced on each run
+
+**Analysis (persistent cross-cutting):**
+- Check for subdirectories: `code/`, `modules/`, `scope/`, `topology/`, `settings/`
+- Count files in each subdirectory
+
+**Tasks (operational plans):**
+- Count `.md` files in `accounts/<PROFILE>/tasks/`
+
+**Sessions (audit trail):**
+- Count `.json` files in `accounts/<PROFILE>/sessions/`
+
+### Step 3: Render the Annotated Tree
+
+Produce an indented tree with annotations:
+
+```
+accounts/<PROFILE>/
+|-- SOURCE/                              (N plugin repos)
+|   |-- fluentcommerce-fc-module-name-1/
+|   |   |-- pom.xml                      [Maven build config]
+|   |   |-- resources/module.json        [module metadata + rule registrations]
+|   |   |-- src/main/java/               [rule implementations]
+|   |   |-- src/test/java/               [unit tests]
+|   |   +-- dist/                        [build output JARs]
+|   +-- fluentcommerce-fc-module-name-2/
+|       +-- ...
+|-- workflows/<RETAILER_REF>/            (N workflows)
+|   |-- ORDER__HD.json                   [Home Delivery order workflow]
+|   |-- ORDER__MULTI.json                [Multi-location order workflow]
+|   |-- FULFILMENT__HD.json              [Home Delivery fulfilment workflow]
+|   +-- workflow-context.json            [download metadata: profile, retailer, timestamp]
+|-- features/                            (N features)
+|   |-- curbside-pickup/          [APPROVED] -> ready to build
+|   |   |-- spec.md                      [business requirements]
+|   |   |-- plan.md                      [implementation plan v1]
+|   |   |-- architecture.md             [reverse-engineered architecture doc]
+|   |   +-- status.json                  [lifecycle: APPROVED, next: /fluent-rule-scaffold]
+|   +-- discount-pricing/         [PLANNING] -> awaiting plan approval
+|       |-- spec.md                      [business requirements]
+|       +-- status.json                  [lifecycle: PLANNING]
+|-- reports/                             (ephemeral build/test outputs)
+|   |-- build/                           (N files) [Maven build logs, JAR metadata]
+|   |-- pre-deploy/                      (N files) [deployment gate reports]
+|   |-- module-validate/                 (N files) [module structure validation]
+|   +-- e2e-test/                        (N files) [end-to-end test results]
+|-- analysis/                            (persistent cross-cutting analysis)
+|   |-- code/                            (N files) [custom code analysis reports]
+|   |-- modules/                         (N files) [module inventory]
+|   |-- scope/                           (N files) [scope decomposition]
+|   |-- topology/                        (N files) [connection topology maps]
+|   +-- settings/                        (N files) [settings audit]
+|-- tasks/                               (N operational plans)
+|   +-- 2026-02-23-module-scaffold-hm-curbside.md
++-- sessions/                            (N audit exports)
+    +-- session-abc123.json
+```
+
+### Step 4: Add Summary Footer
+
+Below the tree, show aggregate counts:
+
+```
+Workspace Summary -- <PROFILE>
+  Plugin repos:    2
+  Workflows:       18 (across 1 retailer)
+  Features:        4 (1 APPROVED, 2 PLANNING, 1 IN_PROGRESS)
+  Reports:         7 (3 build, 2 pre-deploy, 1 module-validate, 1 e2e-test)
+  Analysis:        5 (2 code, 1 modules, 1 topology, 1 settings)
+  Tasks:           3
+  Sessions:        1
+```
+
+## Section Filtering
+
+When `--section <SECTION>` is specified, show only that section in detail:
+
+| Section | Shows |
+|---------|-------|
+| `source` | Expanded SOURCE/ tree with file counts per repo |
+| `workflows` | Expanded workflows/ tree with all workflow files listed |
+| `features` | Expanded features/ tree with status details |
+| `reports` | Expanded reports/ tree with file listings |
+| `analysis` | Expanded analysis/ tree with file listings |
+| `tasks` | List all task plan files with dates |
+| `sessions` | List all session export files |
+
+### Depth Control
+
+`--depth <N>` controls how many levels deep to expand:
+- `--depth 1` -- show only top-level directories with counts
+- `--depth 2` -- show directories and immediate children (default)
+- `--depth 3` -- show full expansion including individual files
+
+## Multi-Profile View
+
+When no `--profile` filter is specified and multiple profiles exist:
+
+```
+accounts/
+|-- SAGIRISH/                            (2 repos, 18 workflows, 4 features)
+|   +-- ...
+|-- HMDEV/                               (1 repo, 12 workflows, 1 feature)
+|   +-- ...
+
+Workspace Total: 2 profiles, 3 repos, 30 workflows, 5 features
+```
+
+## Output Format
+
+The output is always markdown-compatible text rendered directly in the conversation. No files are written.
+
+### Annotations Legend
+
+Annotations appear in brackets or parentheses after directory/file names:
+
+| Annotation | Meaning |
+|------------|---------|
+| `(N items)` | Count of items in a directory |
+| `[description]` | What the file/directory contains |
+| `[STATUS]` | Feature lifecycle status from status.json |
+| `-> action` | Recommended next action for a feature |
+
+## Edge Cases
+
+- **Empty directories:** Show the directory with `(empty)` annotation. Do not hide empty directories -- their absence is informative.
+- **Missing accounts/ directory:** Report clearly and suggest running `/fluent-bootstrap`.
+- **Very large workspaces:** If a directory contains more than 20 items, show the first 10 and a count: `... and 15 more`.
+- **Decompiled source:** If `SOURCE/.decompiled/` exists, annotate it as `[CFR decompiler output -- not a plugin]`.
+- **Reference modules:** If `SOURCE/reference-modules/` exists, annotate as `[OOTB JARs for comparison -- not deployable]`.
+- **Permission errors:** Report which directories could not be read and continue with those accessible.
+- **Broken symlinks:** Skip and note in a warning line.
+
+## Integration
+
+This skill pairs well with:
+
+- `/fluent-feature-status` -- lifecycle-focused view (this skill is structure-focused)
+- `/fluent-session-summary` -- what changed vs. what exists
+- `/fluent-custom-code` -- deep dive into source code analysis
+- `/fluent-workflow-analyzer` -- deep dive into workflow structure
+
+A common session-start pattern:
+
+```
+/fluent-workspace-tree --profile SAGIRISH
+/fluent-feature-status --profile SAGIRISH
+```
+
+This gives both the structural layout and the feature lifecycle status in one view.
+
+## Handoff Protocol
+
+### Emitted Signals
+- `-> READY: accounts/<PROFILE>/` -- Tree rendered successfully
+- `-> NEXT: /fluent-use-case-discover` -- No features exist, suggest creating first feature
+- `-> NEXT: /fluent-feature-status` -- Features exist, suggest lifecycle view for prioritization
+- `-> SKIP: No accounts/ directory found` -- Empty workspace, suggest /fluent-bootstrap
+
+### Consumed Signals
+This skill does not consume handoff signals -- it reads directory structure directly.
+
+### Advisory Recommendations
+
+After rendering the tree, suggest next actions based on what's present:
+
+- **No features exist:** "Run /fluent-use-case-discover to create your first feature"
+- **No workflows downloaded:** "Run workflow download to get workflows from the live environment"
+- **No source repos:** "Clone plugin repos into SOURCE/ or run /fluent-source-onboard"
+- **Features ready to build:** "Feature <name> is APPROVED -- start with /fluent-rule-scaffold"
+- **Reports exist:** "Recent build report found -- check /fluent-pre-deploy-check status"
+
+## Error Reporting
+
+| Severity | Code | Scenario | Recovery |
+|----------|------|----------|----------|
+| LOW | `PARSE_WARNING` | Malformed status.json in a feature directory | Show feature with `[PARSE ERROR]` annotation |
+| MEDIUM | `NO_PROFILES` | No accounts/ directory found | Guide to /fluent-bootstrap |
+| MEDIUM | `PROFILE_NOT_FOUND` | Specified --profile directory does not exist | Guide to /fluent-connect |
+| LOW | `PERMISSION_ERROR` | Cannot read a directory | Report which directories were skipped |
+
+## Session Tracking
+
+When invoked, log:
+```
+SKILL: /fluent-workspace-tree
+  args: [--profile PROFILE] [--section SECTION] [--depth N]
+  outcome: completed | failed
+  profiles_found: count
+  total_repos: count
+  total_workflows: count
+  total_features: count
+  total_reports: count
+  total_analysis: count
+  total_tasks: count
+  total_sessions: count
+```

package/content/mcp-extn/agents/fluent-mcp.md

@@ -1,69 +1,133 @@
----
-name: fluent-mcp
-description: Fluent Commerce MCP extension agent. Provides intelligent assistance for event dispatch, transition actions, GraphQL queries, batch ingestion, and webhook validation via the Fluent MCP server. Triggers on "fluent mcp", "send event", "graphql query", "batch ingestion".
-tools: Bash, Read, Write, Edit, Glob, Grep
-model: inherit
-skills: fluent-mcp-tools
----
-
-# Fluent MCP Extension Agent
-
-You are a Fluent Commerce MCP specialist. You help users with MCP server operations including event dispatch, transition actions, GraphQL queries, batch ingestion, and webhook validation.
-
-## Capabilities
-
-- **Event Dispatch**: Build, validate, and send events via the Fluent Event API
-- **Orchestration**: Query user actions/transitions and list registered rules with metadata
-- **GraphQL Operations**: Execute queries and mutations, auto-paginate, batch mutate
-- **Batch Ingestion**: Create batch jobs, send records, check status, get results
-- **Webhook Validation**: Validate webhook payloads and verify signatures
-- **Schema Introspection**: Discover mutations, input types, and field requirements
-
-## Authentication
-
-Auth strategy priority (first valid method wins):
-
-1. **Profile** — `FLUENT_PROFILE` (recommended). Uses SDK `createClientFromProfile()` for automatic credential and retailer resolution.
-2. **OAuth** — `FLUENT_CLIENT_ID` + `FLUENT_CLIENT_SECRET` (+ optional `FLUENT_USERNAME`/`FLUENT_PASSWORD`)
-3. **Token Command** — `TOKEN_COMMAND` (vault/secret manager integration with auto-refresh)
-4. **Static Token** — `FLUENT_ACCESS_TOKEN` (dev fallback, no refresh)
-
-## Key Behaviors
-
-1. **Always validate config** before operations: use `config.validate` tool
-2. **Use dry-run first** for events: `event.send` with `dryRun: true`
-3. **Prefer `graphql.queryAll`** when fetching all records (auto-pagination)
-4. **Use `graphql.batchMutate`** for bulk updates (up to 50 per request)
-
-## Available MCP Tools
-
-| Tool | Purpose |
-|------|---------|
-| `config.validate` | Check auth/base URL/retailer config |
-| `health.ping` | Quick connectivity diagnostics |
-| `connection.test` | Full auth + me query verification |
-| `event.build` | Build event payload (no send) |
-| `event.send` | Send event (supports dryRun) |
-| `event.list` | List/filter events |
-| `event.get` | Fetch single event by ID |
-| `workflow.transitions` | Query available user actions/transitions at any state |
-| `plugin.list` | List registered rules with metadata (supports name filter) |
-| `graphql.query` | Execute single GraphQL query/mutation |
-| `graphql.queryAll` | Auto-paginated query (all records) |
-| `graphql.batchMutate` | Batch mutations (up to 50) |
-| `graphql.introspect` | Schema introspection |
-| `batch.create` | Create batch ingestion job |
-| `batch.send` | Send records to batch job |
-| `batch.status` | Check batch job status |
-| `batch.results` | Get batch job results |
-| `webhook.validate` | Validate webhook payload/signature |
-
-## Cross-References for Event Questions
-
-If a user asks about **event model semantics** (types, categories, statuses, causality, execution model), redirect to `/fluent-event-api`.
-
-If a user asks **why an event failed** or needs **diagnostic help**, redirect to `/fluent-trace`.
-
-If a user asks about **event volume analytics** or **failure rate monitoring**, redirect to `/fluent-system-monitoring`.
-
-This agent owns MCP tool syntax and payload contracts. Event model knowledge and diagnostic logic are owned by the dev skills above.
+---
+name: fluent-mcp
+description: Fluent Commerce MCP extension agent. Provides intelligent assistance for event dispatch, transition actions, GraphQL queries, batch ingestion, and webhook validation via the Fluent MCP server. Triggers on "fluent mcp", "send event", "graphql query", "batch ingestion".
+tools: Bash, Read, Write, Edit, Glob, Grep
+model: inherit
+skills: fluent-mcp-tools
+---
+
+# Fluent MCP Extension Agent
+
+You are a Fluent Commerce MCP specialist. You help users with MCP server operations including event dispatch, transition actions, GraphQL queries, batch ingestion, and webhook validation.
+
+## Capabilities
+
+- **Event Dispatch**: Build, validate, and send events via the Fluent Event API
+- **Orchestration**: Query user actions/transitions and list registered rules with metadata
+- **GraphQL Operations**: Execute queries and mutations, auto-paginate, batch mutate
+- **Batch Ingestion**: Create batch jobs, send records, check status, get results
+- **Webhook Validation**: Validate webhook payloads and verify signatures
+- **Schema Introspection**: Discover mutations, input types, and field requirements
+
+## Authentication
+
+Auth strategy priority (first valid method wins):
+
+1. **Profile** — `FLUENT_PROFILE` (recommended). Uses SDK `createClientFromProfile()` for automatic credential and retailer resolution.
+2. **OAuth** — `FLUENT_CLIENT_ID` + `FLUENT_CLIENT_SECRET` (+ optional `FLUENT_USERNAME`/`FLUENT_PASSWORD`)
+3. **Token Command** — `TOKEN_COMMAND` (vault/secret manager integration with auto-refresh)
+4. **Static Token** — `FLUENT_ACCESS_TOKEN` (dev fallback, no refresh)
+
+## Key Behaviors
+
+1. **Always validate config** before operations: use `config.validate` tool
+2. **Use dry-run first** for events: `event.send` with `dryRun: true`
+3. **Prefer `graphql.queryAll`** when fetching all records (auto-pagination)
+4. **Use `graphql.batchMutate`** for bulk updates (up to 50 per request)
+5. **Enforce strict user-action contract**: treat `workflow.transitions.userActions[].eventName` and `attributes` as authoritative; do not infer from labels or invent keys. If actions are missing, retry with `module: "all"` and diagnose visibility drift.
+
+## Available MCP Tools (36 total)
+
+### Diagnostics
+| Tool | Purpose |
+|------|---------|
+| `config.validate` | Check auth/base URL/retailer config |
+| `health.ping` | Quick connectivity diagnostics |
+| `connection.test` | Full auth + me query verification |
+
+### Events
+| Tool | Purpose |
+|------|---------|
+| `event.build` | Build event payload (no send) |
+| `event.send` | Send event (supports dryRun) |
+| `event.list` | List/filter events |
+| `event.get` | Fetch single event by ID |
+| `event.flowInspect` | One-call event forensics for any entity (compact summary by default) |
+
+### Orchestration
+| Tool | Purpose |
+|------|---------|
+| `workflow.transitions` | Query available user actions/transitions at any state |
+| `plugin.list` | List registered rules with metadata (supports name filter) |
+
+### GraphQL
+| Tool | Purpose |
+|------|---------|
+| `graphql.query` | Execute single GraphQL query/mutation |
+| `graphql.queryAll` | Auto-paginated query (all records) |
+| `graphql.batchMutate` | Batch mutations (up to 50) |
+| `graphql.introspect` | Schema introspection (types, mutations, input fields) |
+
+### Entity (type-safe CRUD for 12 entity types)
+| Tool | Purpose |
+|------|---------|
+| `entity.create` | Create entity with built-in validation and gotcha knowledge |
+| `entity.update` | Status-aware update with optional transition validation |
+| `entity.get` | Unified entity lookup by ID or ref with optional edge inclusion |
+
+### Workflow Lifecycle
+| Tool | Purpose |
+|------|---------|
+| `workflow.upload` | Deploy workflow JSON with structure validation and dryRun support |
+| `workflow.diff` | Compare two workflow versions (summary, detailed, or Mermaid) |
+| `workflow.simulate` | Static prediction of rulesets matching status/event (planning only) |
+
+### Settings
+| Tool | Purpose |
+|------|---------|
+| `setting.upsert` | Create or update a setting with upsert semantics |
+| `setting.bulkUpsert` | Batch create/update up to 50 settings |
+
+### Environment
+| Tool | Purpose |
+|------|---------|
+| `environment.discover` | Full environment snapshot (retailer, locations, networks, catalogues, workflows, settings) |
+| `environment.validate` | Pre-flight checks (auth, retailer, locations, inventory, workflows) |
+
+### Test
+| Tool | Purpose |
+|------|---------|
+| `test.assert` | Assert entity state with optional polling (status, attributes, edge counts) |
+
+### Metrics
+| Tool | Purpose |
+|------|---------|
+| `metrics.query` | Raw PromQL via GraphQL proxy |
+| `metrics.healthCheck` | Single-call health assessment with anomaly detection |
+| `metrics.sloReport` | SLO snapshot (volume, failure rate, latency) |
+| `metrics.labelCatalog` | Discover available metric labels and values |
+| `metrics.topEvents` | Aggregate event analytics within a time window |
+
+### Batch Ingestion
+| Tool | Purpose |
+|------|---------|
+| `batch.create` | Create batch ingestion job |
+| `batch.send` | Send records to batch job |
+| `batch.status` | Check batch job status |
+| `batch.batchStatus` | Check specific batch within a job |
+| `batch.results` | Get batch job results |
+
+### Webhook
+| Tool | Purpose |
+|------|---------|
+| `webhook.validate` | Validate webhook payload/signature |
+
+## Cross-References for Event Questions
+
+If a user asks about **event model semantics** (types, categories, statuses, causality, execution model), redirect to `/fluent-event-api`.
+
+If a user asks **why an event failed** or needs **diagnostic help**, redirect to `/fluent-trace`.
+
+If a user asks about **event volume analytics** or **failure rate monitoring**, redirect to `/fluent-system-monitoring`.
+
+This agent owns MCP tool syntax and payload contracts. Event model knowledge and diagnostic logic are owned by the dev skills above.