@fluentcommerce/ai-skills 0.1.0 → 0.2.0

package/content/dev/skills/fluent-use-case-discover/SPEC_TEMPLATE.md

@@ -0,0 +1,260 @@
+# Business Spec Template
+
+This is the output template for `/fluent-use-case-discover`. The wizard fills in each section from gathered requirements. Sections marked CONDITIONAL are included only when relevant.
+
+---
+
+## Template
+
+```markdown
+# Business Spec: [Feature Title]
+
+**Status:** DRAFT | REVIEW | APPROVED
+**Date:** YYYY-MM-DD
+**Profile:** <FLUENT_PROFILE>
+**Retailer:** <RETAILER_REF>
+**Requested by:** [stakeholder or team]
+**Completeness:** XX% ([Insufficient / Partial / Sufficient / Complete])
+
+---
+
+## 1. Problem Statement
+
+[Business problem in plain language. What pain exists today? Why does this matter?]
+
+## 2. Feature Summary
+
+[One-sentence description of the feature]
+
+**Type:** [New capability / Enhancement / Bug fix / External integration / Data migration / Process change]
+**Success Metrics:**
+- [KPI 1 — e.g., "Reduce order fulfilment time from 4h to 1h"]
+- [KPI 2 — e.g., "Eliminate manual carrier selection for 90% of orders"]
+
+## 3. Scope
+
+**In scope:**
+- [Bullet list — what this feature will do]
+
+**Out of scope:**
+- [Bullet list — what this feature will NOT do]
+
+## 4. Actors & Triggers
+
+| Actor | Type | Module | Role in Feature |
+|-------|------|--------|-----------------|
+| [e.g., Store associate] | Human | Service Point | Picks and packs items |
+| [e.g., WMS] | System | External | Receives fulfilment requests via webhook |
+| [e.g., Scheduled job] | Automated | Backend | Runs daily reconciliation |
+
+**Trigger:** [What starts this feature — e.g., "New HD order placed via API"]
+
+**Scope:** [Retailer-specific / Account-wide]
+
+## 5. Use Cases
+
+### UC-01: [Happy Path Title]
+
+**Actors:** [list]
+**Preconditions:** [what must be true before this scenario starts]
+**Flow:**
+1. [Step 1 — e.g., "Customer places an HD order via the storefront"]
+2. [Step 2 — e.g., "Order is created in Fluent with status CREATED"]
+3. [Step 3 — ...]
+...
+
+**Postconditions:** [end state — e.g., "Order reaches COMPLETE, customer receives delivery confirmation"]
+
+**Acceptance Criteria:**
+- Given [precondition], When [action], Then [expected result]
+- Given [precondition], When [action], Then [expected result]
+
+### UC-02: [Alternative Path Title]
+
+**Actors:** [list]
+**Preconditions:** [what must be true]
+**Branching condition:** [what makes this path different from UC-01]
+**Flow:**
+1. [...]
+...
+
+**Postconditions:** [end state]
+
+**Acceptance Criteria:**
+- Given [...], When [...], Then [...]
+
+### UC-03: [Exception Path Title]
+
+**Actors:** [list]
+**Preconditions:** [what must be true]
+**Trigger:** [what goes wrong — e.g., "Stock unavailable at allocated location"]
+**Flow:**
+1. [Error handling steps]
+...
+
+**Postconditions:** [recovery state or failure state]
+
+**Acceptance Criteria:**
+- Given [...], When [...], Then [...]
+
+<!-- Add more use cases as needed: UC-04, UC-05, etc. -->
+
+## 6. Entity Model
+
+| Entity | Subtype | New/Existing | Key Attributes | Notes |
+|--------|---------|--------------|----------------|-------|
+| [e.g., Order] | HD | Existing | deliveryWindow (new attr) | Needs new attribute for scheduling |
+| [e.g., Fulfilment] | HD_WH | Existing | carrierRef (existing) | No changes |
+| [e.g., Fulfilment] | CC_STORE | New | pickupCode (new attr) | New subtype for curbside |
+
+**Entity Relationships:**
+[How entities connect in this feature. Example:]
+- Order (HD) creates 1..N Fulfilments (HD_WH or CC_STORE)
+- Fulfilment completion triggers Order status update via cross-entity event
+- Location is referenced by Fulfilment for pick/pack assignment
+
+## 7. Business Rules
+
+| # | Rule Name | Condition | Action | Applies To | Time-Based? |
+|---|-----------|-----------|--------|------------|-------------|
+| BR-01 | [e.g., Stock validation] | If requested qty > available qty | Reject or split | UC-01, UC-02 | No |
+| BR-02 | [e.g., Auto-cancel] | If no pick action within 4 hours | Cancel fulfilment, notify ops | UC-03 | Yes (4h) |
+| BR-03 | [e.g., Carrier routing] | If weight > 30kg | Route to freight carrier | UC-01 | No |
+
+<!-- CONDITIONAL: Only include if Phase 5 was asked -->
+
+## 8. Integrations
+
+| System | Direction | Method | Data Exchanged | Failure Handling |
+|--------|-----------|--------|----------------|------------------|
+| [e.g., WMS] | Fluent → External | Webhook | Fulfilment details (items, qty, location) | Retry 3x (5min interval), then alert ops |
+| [e.g., Carrier API] | Fluent → External | REST API | Shipment request (weight, address, SLA) | Queue for manual retry |
+| [e.g., POS] | External → Fluent | Webhook | Order creation payload | Validate payload, reject malformed |
+
+<!-- CONDITIONAL: Only include if Phase 6 was asked -->
+
+## 9. User Actions
+
+| Action Label | Actor | Available At Status | Form Fields | Confirmation? | Bulk? |
+|-------------|-------|---------------------|-------------|---------------|-------|
+| [e.g., Confirm Pick] | Store associate | PICKING | qty_picked (number, required) | No | No |
+| [e.g., Cancel Order] | Admin | CREATED, BOOKED | reason (dropdown, required) | Yes | Yes |
+| [e.g., Force Complete] | Admin | any except COMPLETE | notes (text, optional) | Yes | No |
+
+<!-- CONDITIONAL: Only include if Phase 7 was asked -->
+
+## 10. Constraints & Risks
+
+| # | Type | Description | Impact | Mitigation |
+|---|------|-------------|--------|------------|
+| R-01 | Risk | [e.g., WMS downtime during peak hours] | Fulfilments delayed | Queue + retry with alerting |
+| R-02 | Risk | [e.g., New subtype may conflict with existing HD rules] | Regression | E2E test before deploy |
+| C-01 | Constraint | [e.g., Must not break existing HD flow] | Regression | Test existing flow after changes |
+| C-02 | Constraint | [e.g., Must handle 500 orders/hour at peak] | Performance | Load test before go-live |
+
+**Volume expectations:** [e.g., "~200 orders/day normal, ~500/day peak (Black Friday)"]
+
+## 11. Assumptions
+
+- [A-01] [e.g., Existing inventory catalogue has accurate stock levels]
+- [A-02] [e.g., WMS webhook endpoint is already deployed and accepts JSON]
+- [A-03] [e.g., Store associates have Service Point access configured]
+...
+
+**Important:** Assumptions become risks if proven wrong. Each should be validated during the feature plan phase.
+
+## 12. Open Questions
+
+- [Q-01] [e.g., What is the SLA for WMS response time?] — **Blocks:** BR-02 (auto-cancel timing)
+- [Q-02] [e.g., Should partial picks be allowed or must the full qty be picked?] — **Blocks:** UC-02 definition
+- [Q-03] [e.g., Which carrier API version are we targeting?] — **Blocks:** Integration design
+...
+
+**Important:** Open questions MUST be resolved before the feature plan can be completed. Each question notes which spec section it blocks.
+
+## 13. Acceptance Criteria Summary
+
+| UC | Criteria | Priority |
+|----|----------|----------|
+| UC-01 | Given stock available at warehouse, When HD order placed, Then fulfilment created and assigned within 30s | Must-have |
+| UC-02 | Given partial stock across locations, When HD order placed, Then order split into multiple fulfilments | Must-have |
+| UC-03 | Given no stock available, When HD order placed, Then customer notified and order moved to BACKORDER | Must-have |
+| UC-01 | Given fulfilment shipped, When carrier confirms delivery, Then order status updated to COMPLETE | Must-have |
+| UC-01 | Given peak load (500 orders/hour), When orders placed, Then all processed within 60s | Nice-to-have |
+
+---
+
+## Traceability Matrix
+
+| Use Case | Entities | Business Rules | Integrations | User Actions |
+|----------|----------|----------------|--------------|--------------|
+| UC-01 | Order (HD), Fulfilment (HD_WH) | BR-01, BR-03 | WMS, Carrier | Confirm Pick |
+| UC-02 | Order (HD), Fulfilment x2 | BR-01 | WMS | Confirm Pick |
+| UC-03 | Order (HD) | BR-02 | Notification | — |
+
+This matrix ensures every use case traces through to entities, rules, integrations, and actions. Gaps in this table indicate incomplete requirements.
+
+---
+
+## Recommendation
+
+[Auto-generated by the wizard based on completeness score:]
+
+**Score: XX% — [Insufficient / Partial / Sufficient / Complete]**
+
+[One of:]
+- "This spec is **ready for technical planning**. Run `/fluent-feature-plan` to produce the implementation plan."
+- "This spec is **sufficient but has gaps** in [Phase X, Phase Y]. The feature plan can proceed but will make assumptions for those sections. Consider resolving open questions Q-01 and Q-02 first."
+- "This spec has **too many gaps** to produce a reliable feature plan. Address: [list of missing phases]. Focus on [highest-priority gap]."
+
+## Next Step
+
+When this spec is APPROVED, proceed to technical implementation planning:
+
+```
+/fluent-feature-plan --spec accounts/<PROFILE>/analysis/specs/<YYYY-MM-DD>-<slug>.md
+```
+```
+
+---
+
+## Section Applicability Guide
+
+| Section | Always? | When to Include |
+|---------|---------|-----------------|
+| §1 Problem Statement | YES | Every spec |
+| §2 Feature Summary | YES | Every spec |
+| §3 Scope | YES | Every spec |
+| §4 Actors & Triggers | YES | Every spec |
+| §5 Use Cases | YES | Every spec (minimum: happy path + 1 exception) |
+| §6 Entity Model | YES | Every Fluent feature |
+| §7 Business Rules | CONDITIONAL | When there are decision points, validations, or calculations |
+| §8 Integrations | CONDITIONAL | When external systems are involved |
+| §9 User Actions | CONDITIONAL | When human actors interact via Fluent UI |
+| §10 Constraints & Risks | YES | Every spec (even if brief) |
+| §11 Assumptions | YES | Every spec |
+| §12 Open Questions | YES | Every spec (can be empty if fully resolved) |
+| §13 Acceptance Criteria | YES | Every spec |
+| Traceability Matrix | YES | Every spec |
+
+## Completeness Scoring Rubric
+
+| Phase | Weight | Full Score | Half Score | Zero |
+|-------|--------|------------|------------|------|
+| 1. Feature Identity | 15% | All REQUIRED questions answered | Problem + summary but no metrics | Missing problem statement |
+| 2. Actors & Triggers | 10% | Actors + trigger + scope identified | Trigger only, no actors | Neither identified |
+| 3. Use Cases | 20% | Happy path + alternative + exception | Happy path only | No use cases defined |
+| 4. Entities & Data | 15% | All entities with subtypes + attributes | Entities listed, no subtypes | No entities identified |
+| 5. Business Rules | 15% | Rules per decision point in use cases | Some rules, gaps in coverage | N/A → 0% weight redistributed |
+| 6. Integrations | 5% | All systems with method + failure handling | Systems listed, no details | N/A → 0% weight redistributed |
+| 7. UI Actions | 5% | Actions per actor with status + fields | Actions listed, no details | N/A → 0% weight redistributed |
+| 8. Constraints | 5% | Risks + assumptions + volume documented | At least one risk or assumption | Nothing documented |
+| 9. Acceptance Criteria | 10% | Given/When/Then per use case + priority | Some criteria, not per UC | No acceptance criteria |
+
+**When N/A phases exist:** Their weight is redistributed proportionally across applicable phases. A backend-only feature with no integrations redistributes 10% (Phase 6 + 7) across the remaining phases.
+
+**Score interpretation:**
+- **90-100%:** Complete — comprehensive, minimal assumptions needed
+- **75-89%:** Sufficient — ready for feature plan, minor gaps flagged
+- **50-74%:** Partial — can proceed but assumption-heavy
+- **< 50%:** Insufficient — too many gaps to produce reliable plan

package/content/dev/skills/fluent-version-manage/SKILL.md

@@ -14,6 +14,16 @@ Manage the full version lifecycle for Fluent Commerce extension modules: read cu
 
 ## Planning Gate
 
+### Pre-flight: Plan Verification
+
+Before proceeding, check for an existing approved plan:
+
+1. **Search** `accounts/<PROFILE>/plans/` for a file with `Status: APPROVED` that covers this version change
+2. **If multi-artifact work** (version bump as part of feature delivery): 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 version-only work with no plan:** Continue to the Planning Gate below to write a plan for this skill
+5. **`status` (read-only) and `sync --dry-run`** are always exempt from planning
+
 **Before bumping versions, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** `status` (read-only) and `sync --dry-run` are exempt.
 
 **Version-manage specific emphasis — ensure these are covered:**

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

@@ -12,6 +12,15 @@ Create, edit, and validate Fluent Commerce workflow JSON definitions.
 
 ## Planning Gate
 
+### Pre-flight: Plan Verification
+
+Before proceeding, check for an existing approved plan:
+
+1. **Search** `accounts/<PROFILE>/plans/` for a file with `Status: APPROVED` that covers this workflow
+2. **If multi-artifact work** (workflow + rules + 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 §4 (Workflows), §5 (Statuses), and §6 (Rulesets) sections
+4. **If single-workflow-only work with no plan:** Continue to the Planning Gate below to write a plan for this skill
+
 **Before creating or modifying any workflow, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** Every table row must carry a Source column (NEW/EXISTING/MODIFIED/REUSED/OOTB).
 
 **If this workflow change is part of a larger feature** (rules + settings + webhooks), use `/fluent-feature-plan` first. Then reference the approved plan during implementation.
@@ -273,9 +282,7 @@ Find the gate ruleset, update the `statuses` prop value.
 
 ### Upload/merge
 
-Use `/fluent-workflow-deploy` for uploading workflows to environments (MCP tool primary, REST API fallback). Use `/fluent-workflow` for listing, downloading, and merging workflows. Use `/fluent-module-deploy` for deploying full module bundles (JAR + settings + workflows together).
-
-**Important:** If the workflow references new custom rules, deploy the module first via `/fluent-module-deploy` before uploading the workflow. Unregistered rules cause NO_MATCH events at runtime.
+Use `/fluent-workflow` for merge/upload workflows and `/fluent-module-deploy` (or `flow-run`) for deployment execution.
 
 ## Workflow Fragments
 

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

@@ -35,27 +35,90 @@ Auth strategy priority (first valid method wins):
 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
+## 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 |
+| `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