@fluentcommerce/ai-skills 0.1.0 → 0.3.0

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

@@ -0,0 +1,281 @@
+# 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]
+
+## 3a. Existing State (conditional — include when extending an existing feature)
+
+> Include this section when the feature extends, modifies, or builds on an existing Fluent Commerce feature. Skip for greenfield features.
+
+If an architecture document exists at `features/<parent-slug>/architecture.md` (produced by `/fluent-feature-explain`), reference it here.
+
+### Current Architecture Reference
+- **Parent feature:** `<parent-slug>`
+- **Architecture doc:** `features/<parent-slug>/architecture.md`
+- **basedOn field in status.json:** `"basedOn": "<parent-slug>"`
+
+### What Exists Today
+| Artifact | Current State | To Be Modified? |
+|----------|--------------|-----------------|
+| Workflow `ORDER::HD` | v1.56, 14 rulesets | Yes — adding new ruleset |
+| Rule `CreateFulfilment` | OOTB, no customization | Yes — replacing with custom |
+| Settings `FULFILMENT_SPLIT_*` | Not present | New — to be created |
+
+### What This Feature Changes
+Describe the delta from current state. What's being added, modified, or removed? This section bridges the gap between the architecture doc (what IS) and the spec (what SHOULD BE).
+
+## 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 --feature <slug>
+```
+```
+
+---
+
+## 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>/features/*/status.json` for an entry with `plan: "APPROVED"` that covers this version change, OR check `accounts/<PROFILE>/tasks/` for a task plan with `Status: APPROVED`
+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:**
@@ -24,7 +34,7 @@ Manage the full version lifecycle for Fluent Commerce extension modules: read cu
 4. **Detailed Design (Section 5)** — CHANGELOG entries to move from [Unreleased] to new version heading
 5. **Impacted retailers (Section 4.8)** — which environments will receive this version
 
-**Write the plan to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-version-manage-<slug>.md`. Set `Status: PENDING`.
+**Write the plan to:** `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-version-manage-<slug>.md`. Set `Status: PENDING`.
 
 Present the full plan content to the user and wait for approval before modifying any version files. On approval, update the file to `Status: APPROVED`. If the user says "just do it", proceed directly (still write the file for audit trail).
 
@@ -64,6 +74,23 @@ The existing `/fluent-build` skill has a "Version Bump" section (step 1 of 4). T
 | Git commit | None | Optional `--commit` flag |
 | SNAPSHOT handling | None | Strips `-SNAPSHOT` suffix during bump |
 
+## Handoff Protocol
+
+### Signals emitted by this skill
+
+| Signal | Condition | Example |
+|--------|-----------|---------|
+| `-> READY: <path>` | Version bumped | `-> READY: Version bumped 0.0.29 -> 0.0.30 in pom.xml + module.json` |
+| `-> NEXT: /fluent-<skill>` | Ready for build | `-> NEXT: /fluent-build` |
+| `-> SKIP: <reason>` | Status/dry-run (exempt from planning) | `-> SKIP: Version status check only — no changes made` |
+
+### Error codes
+
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| `PLAN_REQUIRED` | Version bump attempted without approved plan | Run `/fluent-feature-plan` first |
+| `VALIDATION_FAILED` | Invalid version format or conflict | Fix version string and retry |
+
 ## When to Use
 
 - "What version is this module?" -> `status`
@@ -479,6 +506,13 @@ To push the tag to remote:
 
 The `bump` command transforms CHANGELOG.md by moving the `[Unreleased]` section contents under a new dated version heading.
 
+**Preview mode:** Before applying CHANGELOG transforms, use `--dry-run` to preview what will change:
+- Show which entries will move from `[Unreleased]` to the new version heading
+- Show the new version heading format
+- Do not modify any files
+
+This prevents accidental CHANGELOG corruption when version numbers are wrong.
+
 ### Expected CHANGELOG Format (Keep a Changelog)
 
 ```markdown
@@ -502,6 +536,23 @@ The `bump` command transforms CHANGELOG.md by moving the `[Unreleased]` section
 ...
 ```
 
+### Dry-Run Preview
+
+Before transforming the CHANGELOG, **always show a preview** of what will change:
+
+```
+/fluent-version-manage bump --level patch --dry-run
+```
+
+In dry-run mode:
+1. Read CHANGELOG.md and extract the `[Unreleased]` section
+2. Show the user what the new version heading will look like
+3. Show what content will move from `[Unreleased]` to the new heading
+4. Do NOT write any changes
+5. Wait for user confirmation before applying
+
+This prevents accidental CHANGELOG corruption, especially when the `[Unreleased]` section is empty or the format doesn't match expectations.
+
 ### Transformation Algorithm
 
 ```
@@ -667,7 +718,7 @@ When `--module-path` is not provided, search for the module root automatically:
 Before running, check if `/fluent-custom-code` artifacts exist:
 
 ```
-accounts/<PROFILE>/analysis/custom-code/source-map.json
+accounts/<PROFILE>/analysis/code/source-map.json
 ```
 
 If found, read `modules[].version` and `modules[].versionSource` to pre-populate version information without re-scanning POM files. Fall back to direct file reads if artifacts are missing or stale.