@fluentcommerce/ai-skills 0.2.0 → 0.3.0

package/docs/DESIGN-implementation-map.md

@@ -0,0 +1,698 @@
+# Design: `/fluent-implementation-map` Skill
+
+**Status:** Implemented (2026-02-25)
+**Implementation:** `content/dev/skills/fluent-implementation-map/SKILL.md`
+**Author:** Auto-generated design document
+**Date:** 2026-02-25
+
+> **Note:** This document contains design rationale, architectural context, and decision trail.
+> For usage instructions, see the SKILL.md. For the E2E test run, see `accounts/SAGIRISH/analysis/implementation-map/`.
+
+## Problem
+
+When onboarding to an existing Fluent Commerce account — or auditing one you haven't touched in months — there is no single command that answers:
+
+> "What has been built here, how does it all fit together, and what are the end-to-end flows?"
+
+Today you must manually invoke 4-6 skills in sequence, stitch the outputs together in your head, and hope you didn't miss a cross-entity handoff or an orphaned customisation. This is the most common first question for any new implementation engagement.
+
+## What Exists Today
+
+| Skill | Scope | Limitation |
+|-------|-------|------------|
+| `/fluent-feature-explain` | Single named feature → Architecture Document | You must already know the feature name and boundaries |
+| `/fluent-workflow-analyzer` | Single workflow JSON → structure, orphans, triggers | Per-workflow; no cross-workflow or cross-entity view |
+| `/fluent-connection-analysis` | Cross-workflow topology map, static-vs-dynamic diff | Maps connections but doesn't identify logical features |
+| `/fluent-custom-code` | Source code analysis under SOURCE/ | Per-module; no link back to which business flow uses it |
+| `/fluent-workspace-tree` | Directory structure + artifact counts | Structural, not semantic |
+| `/fluent-feature-status` | Dashboard of existing feature directories | Only shows features that have already been decomposed |
+| `/fluent-scope-decompose` | Breaks a scope doc into tasks | Works from documents, not from a live implementation |
+
+**The gap:** No skill starts from "I know nothing about this account" and produces a complete feature-level decomposition with end-to-end flows.
+
+## Proposed Skill: `/fluent-implementation-map`
+
+### One-liner
+
+Reverse-engineer an entire Fluent Commerce implementation into a feature inventory with end-to-end flow diagrams, cross-feature dependencies, and gap analysis.
+
+### Invocation
+
+```
+/fluent-implementation-map --profile SAGIRISH --retailer "Module Test"
+/fluent-implementation-map --profile HMDEV --retailer HM_TEST --depth summary
+/fluent-implementation-map --profile HMDEV --retailer HM_TEST --depth detailed
+/fluent-implementation-map --profile HMDEV --retailer HM_TEST --focus ORDER
+```
+
+### Parameters
+
+| Parameter | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `--profile` | Yes | Active CLI profile | Fluent CLI profile |
+| `--retailer` | Yes | Profile default | Target retailer ref |
+| `--depth` | No | `summary` | `summary` = feature list + high-level flows; `detailed` = full per-feature architecture |
+| `--focus` | No | All | Filter to specific entity type (ORDER, FULFILMENT, ARTICLE, etc.) |
+| `--include-ootb` | No | `false` | Include OOTB-only flows (no customisations) in the map |
+| `--create-stubs` | No | `false` | Create `features/<slug>/status.json` for each discovered feature, bridging discovery into the feature lifecycle |
+| `--include-runtime` | No | `false` | Collect runtime evidence per feature via `event.flowInspect` and `entity.get` (significantly slower) |
+
+### Output
+
+Written to: `accounts/<PROFILE>/analysis/implementation-map/`
+
+```
+accounts/<PROFILE>/analysis/implementation-map/
+├── implementation-map.md          # Master document: feature inventory + cross-feature map
+├── features/                      # Per-feature summaries (auto-generated, not lifecycle-managed)
+│   ├── home-delivery-order.md
+│   ├── click-collect-order.md
+│   ├── fulfilment-hd.md
+│   ├── sourcing-allocation.md
+│   └── ...
+├── diagrams/                      # Mermaid source files
+│   ├── feature-dependency.mmd     # Cross-feature dependency graph
+│   ├── entity-flow.mmd           # Entity lifecycle overview
+│   └── <feature>-flow.mmd        # Per-feature flow diagram
+├── gaps.md                        # Orphaned rules, unused settings, dead-end states
+└── inventory.json                 # Machine-readable: all workflows, rules, settings, feature clusters
+```
+
+**Important:** These are analysis artifacts, NOT feature lifecycle artifacts. They live under `analysis/`, not `features/`. If the user wants to turn a discovered feature into a lifecycle-managed feature, they run `/fluent-use-case-discover` or `/fluent-feature-explain` to create `features/<slug>/`.
+
+---
+
+## How It Works: 5 Phases
+
+### Phase 1: Inventory Collection (read-only, parallelisable)
+
+Collect all raw data from the environment. This phase invokes existing skills and MCP tools.
+
+#### 1a. Workflows
+
+```
+Invoke: fluent workflow list -p <PROFILE> -r <RETAILER>
+Invoke: fluent workflow download (if not already cached locally)
+Read:   accounts/<PROFILE>/workflows/<RETAILER>/*.json
+```
+
+Produces: List of all workflow names, entity types, subtypes.
+
+**Entity type extraction:** Parse workflow JSON `name` field. Convention: `<ENTITY_TYPE>::<SUBTYPE>` (e.g., `ORDER::HD`, `FULFILMENT::CC`, `ARTICLE::DEFAULT`). If no `::`, treat as entity type with DEFAULT subtype.
+
+#### 1b. Custom Rules (deployed)
+
+```
+Invoke: MCP plugin.list (live environment)
+```
+
+Produces: List of all deployed rules with module, version, and rule key.
+
+#### 1c. Custom Rules (source code)
+
+```
+Scan:   accounts/<PROFILE>/SOURCE/*/resources/module.json
+Scan:   accounts/<PROFILE>/SOURCE/*/src/main/java/**/*.java
+```
+
+Produces: Per-rule metadata (class name, annotations, entity context, referenced settings).
+
+#### 1d. Settings
+
+```
+Invoke: MCP graphql.query — query settings by context (RETAILER, ACCOUNT)
+  OR
+Invoke: fluent setting list -p <PROFILE> -r <RETAILER> -q '*'
+```
+
+Produces: All settings with their keys, values, and contexts.
+
+#### 1e. Entity Type Catalogue
+
+```
+Invoke: MCP graphql.query — list entity types and subtypes in use
+  Suggested query: orderTypes, fulfilmentTypes, articleTypes, etc.
+```
+
+Produces: Which entity types and subtypes are configured.
+
+#### 1f. Webhook / Integration Inventory
+
+```
+Grep:   Workflow JSONs for SendWebhook rule invocations
+Grep:   Settings for webhook-related keys (*.url, *.endpoint, webhook.*)
+```
+
+Produces: Outbound integration points.
+
+### Phase 2: Feature Identification (analytical, no external calls)
+
+This is the core intelligence of the skill. It groups raw inventory into logical features.
+
+#### 2a. Primary Grouping: Entity Type + Subtype
+
+Each workflow defines a scope of entity management. Group workflows by entity type:
+
+```
+ORDER workflows:       ORDER::HD, ORDER::CC, ORDER::MULTI
+FULFILMENT workflows:  FULFILMENT::HD, FULFILMENT::CC
+ARTICLE workflows:     ARTICLE::DEFAULT
+WAVE workflows:        WAVE::DEFAULT
+```
+
+#### 2b. Feature Boundary Heuristics
+
+A "feature" is a user-facing business capability that typically spans one or more entity types. Heuristics for identifying feature boundaries:
+
+1. **Subtype alignment**: An ORDER subtype (e.g., `HD`) usually pairs with a FULFILMENT subtype (e.g., `HD`) → group as one feature "Home Delivery"
+2. **Cross-entity events**: If ORDER::HD sends events that FULFILMENT::HD workflows consume → same feature
+3. **Shared custom rules**: If a custom rule is referenced by both ORDER::HD and FULFILMENT::HD workflows → same feature
+4. **Naming convention**: Subtypes with the same suffix (HD, CC, MULTI) suggest feature families
+5. **Standalone entity types**: WAVE, ARTICLE often serve infrastructure rather than a single feature — mark as "shared infrastructure"
+
+#### 2b-ii. Confidence Levels
+
+Each feature cluster carries a confidence indicator:
+
+| Level | Meaning | Trigger |
+|-------|---------|---------|
+| `HIGH` | Subtype family match + event chain confirmed | Heuristics 1+2 agree |
+| `MEDIUM` | Subtype family match only (no event chain confirmation) | Heuristic 1 only |
+| `INFERRED` | Naming/rule pattern analysis | Heuristic 3 fallback |
+| `UNCLUSTERED` | Could not assign to any feature | No heuristic matched |
+
+#### 2c. Feature Classification
+
+| Category | Definition | Example |
+|----------|-----------|---------|
+| **Business Feature** | End-to-end customer-facing flow spanning ORDER→FULFILMENT | Home Delivery, Click & Collect |
+| **Processing Feature** | Backend automation within a single entity type | Wave management, Article pick/pack |
+| **Infrastructure** | Shared services consumed by multiple features | Sourcing, Inventory, Settings |
+| **Integration** | Outbound/inbound data flows to external systems | Webhook delivery, Batch ingestion |
+
+#### 2d. Customisation Depth Scoring
+
+For each identified feature, score the customisation depth:
+
+| Score | Meaning | Criteria |
+|-------|---------|----------|
+| 0 — OOTB | No customisations | All rules are OOTB, no custom settings |
+| 1 — Configured | OOTB rules with custom settings/props | OOTB rules but custom prop values or settings |
+| 2 — Extended | Mix of OOTB and custom rules | Some custom rules alongside OOTB |
+| 3 — Custom | Mostly custom rules | >50% of rules in the workflow are custom |
+| 4 — Bespoke | Entirely custom implementation | All rules are custom, non-standard entity usage |
+
+### Phase 3: Flow Mapping (per feature)
+
+For each identified feature, trace the complete end-to-end flow.
+
+#### 3a. Entry Point Identification
+
+- What triggers this feature? (User action, scheduled event, inbound webhook, batch ingestion)
+- What entity is created/modified first?
+- What status does the entity start in?
+
+#### 3b. Workflow Path Tracing
+
+For each workflow in the feature:
+
+```
+For each ruleset in workflow:
+  - Trigger: status + event name
+  - Rules: ordered list of rule keys (mark OOTB vs CUSTOM)
+  - Outcomes: status transitions (success path, error path)
+  - Cross-entity handoffs: events sent to other entity types
+  - Settings consumed: rule prop references to settings keys
+  - Webhooks fired: SendWebhook invocations with target URLs
+```
+
+#### 3c. Cross-Entity Flow Stitching
+
+Follow the chain across entity types:
+
+```
+ORDER::HD (BOOKED)
+  → CreateFulfilment rule
+    → FULFILMENT::HD created (CREATED)
+      → AllocateArticles rule
+        → ARTICLE created (CREATED)
+          → ...
+```
+
+This requires matching:
+- `SendEvent` rule outputs in workflow A → `eventName` triggers in workflow B
+- `CreateEntity` rule invocations → entity type + subtype + initial status → matching workflow
+
+#### 3d. Mermaid Diagram Generation
+
+For each feature, generate:
+
+**Sequence diagram** (entity lifecycle):
+```mermaid
+sequenceDiagram
+    participant OMS as ORDER::HD
+    participant FUL as FULFILMENT::HD
+    participant ART as ARTICLE
+
+    OMS->>OMS: CREATED → BOOKED (SourceOrder)
+    OMS->>FUL: CreateFulfilment
+    FUL->>ART: AllocateArticles
+    ART->>ART: CREATED → ACTIVE (AssignLocation)
+    ART-->>FUL: ArticleComplete event
+    FUL->>OMS: FulfilmentComplete event
+```
+
+**State diagram** (per entity):
+```mermaid
+stateDiagram-v2
+    [*] --> CREATED
+    CREATED --> BOOKED: SourceOrder
+    BOOKED --> FULFILLED: AllItemsComplete
+    FULFILLED --> COMPLETE: CompleteOrder
+```
+
+### Phase 4: Gap Analysis
+
+#### 4a. Orphaned Rules
+Rules registered in `module.json` or deployed via `plugin.list` but NOT referenced in any workflow ruleset.
+
+```
+Invoke (internally): /fluent-workflow-analyzer orphan detection logic
+Cross-reference: plugin.list output vs. all workflow rule references
+```
+
+#### 4b. Unused Settings
+Settings that exist in the environment but are not referenced by any rule (via prop values or direct setting reads).
+
+```
+Cross-reference: settings list vs. rule prop definitions in workflow JSONs
+```
+
+#### 4c. Dead-End States
+Workflow states with no outbound transitions (not marked as terminal/final).
+
+```
+Invoke (internally): /fluent-workflow-analyzer state graph analysis
+```
+
+#### 4d. Missing Cross-Entity Handlers
+Events sent by one workflow that no other workflow has a trigger for.
+
+```
+Invoke (internally): /fluent-connection-analysis cross-entity event matching
+```
+
+#### 4e. Undocumented Customisations
+Custom rules with no Javadoc, no test class, or no matching feature documentation.
+
+```
+Cross-reference: SOURCE/ Java files vs. features/ directory for documentation
+```
+
+### Phase 5: Report Generation
+
+#### Master Document (`implementation-map.md`)
+
+```markdown
+# Implementation Map: <RETAILER> on <PROFILE>
+
+Generated: <timestamp>
+Environment: <base-url>
+
+## Executive Summary
+
+| Metric | Count |
+|--------|-------|
+| Workflows | 18 |
+| Custom rules (deployed) | 45 |
+| Custom rules (source) | 52 |
+| Settings | 120 |
+| Identified features | 8 |
+| Shared infrastructure | 3 |
+| Integrations | 5 |
+| Customisation depth (avg) | 2.4 / 4 |
+
+## Feature Inventory
+
+| # | Feature | Category | Entity Types | Customisation | Workflows | Custom Rules | Key Integration |
+|---|---------|----------|-------------|---------------|-----------|-------------|-----------------|
+| 1 | Home Delivery | Business | ORDER::HD, FULFILMENT::HD, ARTICLE | 3 — Custom | 3 | 12 | Webhook: shipping |
+| 2 | Click & Collect | Business | ORDER::CC, FULFILMENT::CC | 2 — Extended | 2 | 5 | — |
+| 3 | Sourcing | Infrastructure | — (invoked within ORDER flows) | 3 — Custom | 0 | 3 | — |
+| ... | | | | | | | |
+
+## Cross-Feature Dependency Map
+
+[Mermaid diagram: which features depend on which]
+
+## Per-Feature Summaries
+
+### 1. Home Delivery
+
+**Entry point:** Order created via API with type=HD
+**End state:** ORDER::HD reaches COMPLETE
+**Flow:** ORDER::HD → FULFILMENT::HD → ARTICLE → (pick/pack/ship) → COMPLETE
+**Custom rules:** CreateFulfilmentFromSourcingLocation, CalculateShippingCost, ...
+**Settings:** 15 (webhook.shipping.url, fulfilment.hd.auto-complete, ...)
+**Integrations:** Outbound webhook to shipping provider
+
+[Link to detailed flow: features/home-delivery-order.md]
+
+### 2. Click & Collect
+...
+
+## Gaps & Risks
+
+| # | Type | Description | Severity | Recommendation |
+|---|------|-------------|----------|----------------|
+| 1 | Orphaned Rule | `LegacyDiscountRule` deployed but not in any workflow | LOW | Remove or document |
+| 2 | Dead-End State | FULFILMENT::HD `ON_HOLD` has no outbound transition | MEDIUM | Add manual release path |
+| 3 | Missing Handler | ORDER::HD sends `FulfilmentException` but no workflow handles it | HIGH | Add error handling ruleset |
+```
+
+---
+
+## Skills Invoked (Orchestration Map)
+
+The implementation-map skill is an **orchestrator** that invokes existing skills and MCP tools. It should NOT duplicate their logic.
+
+### Required Invocations
+
+| Phase | Tool/Skill | Purpose | Parallelisable? |
+|-------|-----------|---------|-----------------|
+| 1a | `fluent workflow list` (CLI) | Enumerate workflows | Yes |
+| 1a | `fluent workflow download` (CLI) | Cache workflow JSONs locally | Yes (after list) |
+| 1b | `plugin.list` (MCP) | Deployed rule inventory | Yes |
+| 1c | Glob + Read (local) | Source code analysis | Yes |
+| 1d | `graphql.query` (MCP) or CLI settings | Settings inventory | Yes |
+| 1e | `graphql.query` (MCP) | Entity type catalogue | Yes |
+| 1f | Grep (local) | Webhook/integration extraction from workflow JSONs | Yes |
+| 2 | Internal logic | Feature identification (no external calls) | N/A |
+| 3 | Internal logic + `/fluent-connection-analysis` patterns | Flow tracing | Per-feature |
+| 4a | `/fluent-workflow-analyzer` logic | Orphan detection | Yes |
+| 4b | Cross-reference (internal) | Unused settings | Yes |
+| 4c | `/fluent-workflow-analyzer` logic | Dead-end states | Yes |
+| 4d | `/fluent-connection-analysis` logic | Missing handlers | Yes |
+| 5 | Write (local) | Report generation | Sequential |
+
+### Optional Follow-up Invocations
+
+After the map is generated, the user can drill deeper:
+
+| User Request | Skill to Invoke |
+|-------------|-----------------|
+| "Explain feature X in detail" | `/fluent-feature-explain --feature <slug>` |
+| "I want to extend feature X" | `/fluent-use-case-discover` (with `extends: <slug>`) |
+| "Turn this into lifecycle features" | `/fluent-scope-decompose` (from the feature inventory) |
+| "What's the full connection map?" | `/fluent-connection-analysis --validate` |
+| "Analyze the custom code" | `/fluent-custom-code` |
+| "Check if this is production-ready" | `/fluent-rfl-assess` |
+
+---
+
+## Implementation Considerations
+
+### Skill Frontmatter
+
+```yaml
+---
+name: fluent-implementation-map
+description: Reverse-engineer an entire Fluent Commerce implementation into a feature inventory with end-to-end flows, cross-feature dependencies, and gap analysis. Triggers on "implementation map", "what's been built", "analyze implementation", "reverse engineer account", "feature inventory", "end to end flows", "map this account".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: --profile PROFILE --retailer RETAILER [--depth summary|detailed] [--focus ENTITY_TYPE]
+---
+```
+
+### Planning Gate
+
+**No.** This is a read-only analysis skill. It writes analysis artifacts to `analysis/implementation-map/` but does not modify workflows, settings, or entities. Same category as `/fluent-feature-explain` and `/fluent-workflow-analyzer`.
+
+### MCP Tool Dependencies
+
+The skill needs MCP tools to be available for full capability:
+
+| MCP Tool | Used For | Graceful Degradation |
+|----------|----------|---------------------|
+| `plugin.list` | Deployed rule inventory | Fall back to SOURCE/ scan only |
+| `graphql.query` | Settings, entity types | Fall back to CLI commands or skip |
+| `workflow.transitions` | Live workflow versions | Fall back to local JSON only |
+
+If MCP is unavailable, the skill should still work from local files (downloaded workflows + SOURCE/) with reduced coverage. Report which phases were skipped.
+
+### Size & Complexity
+
+This is one of the larger skills. Estimated SKILL.md size: 400-600 lines. The core complexity is in Phase 2 (feature identification heuristics) and Phase 3 (cross-entity flow stitching).
+
+Consider splitting into two files if it exceeds 500 lines:
+- `SKILL.md` — main skill with phases 1-5
+- `HEURISTICS.md` — companion doc with detailed feature identification rules and examples
+
+### Relationship to Existing Skills
+
+```
+/fluent-implementation-map (NEW — discovers everything, produces feature inventory)
+    ├── /fluent-feature-explain (EXISTING — deep-dive single feature)
+    ├── /fluent-workflow-analyzer (EXISTING — per-workflow structure)
+    ├── /fluent-connection-analysis (EXISTING — topology map)
+    ├── /fluent-custom-code (EXISTING — source code analysis)
+    └── /fluent-scope-decompose (EXISTING — can consume the feature inventory)
+```
+
+The implementation-map skill is the **top of the analysis pyramid**. It's the first thing you run. Everything else drills deeper.
+
+### Handoff Protocol
+
+```
+-> READY: accounts/<PROFILE>/analysis/implementation-map/implementation-map.md
+-> NEXT: /fluent-feature-explain --feature "<slug>" (for any feature needing deeper analysis)
+-> NEXT: /fluent-scope-decompose (to convert inventory into lifecycle features)
+-> NEXT: /fluent-rfl-assess (for production readiness check)
+-> BLOCKED: No workflows found. Download workflows first: fluent workflow download -p <PROFILE> -r <RETAILER>
+```
+
+### Agent Registration
+
+Add to `fluent-dev` agent (`content/dev/agents/fluent-dev.md`) trigger list:
+- "implementation map", "what's been built", "analyze implementation", "reverse engineer account", "feature inventory", "map this account", "end to end flows", "onboard to account", "what exists"
+
+Add to `metadata.json` in the `dev` group skills array.
+
+---
+
+## Worked Example
+
+Given an account with these workflows:
+- `ORDER::HD`, `ORDER::CC`, `ORDER::MULTI`
+- `FULFILMENT::HD`, `FULFILMENT::CC`
+- `ARTICLE::DEFAULT`
+- `WAVE::DEFAULT`
+
+And these custom rules (from plugin.list):
+- `CreateFulfilmentFromSourcingLocation` (ORDER context)
+- `CalculateShippingCost` (FULFILMENT context)
+- `AutoCompleteOrder` (ORDER context)
+- `NotifyCustomerViaWebhook` (FULFILMENT context)
+- `BulkArticleStatusUpdate` (ARTICLE context)
+- `CustomSourceOrder` (ORDER context)
+
+**Phase 2 would identify:**
+
+| Feature | Why |
+|---------|-----|
+| Home Delivery (HD) | ORDER::HD + FULFILMENT::HD share `HD` subtype; `CreateFulfilmentFromSourcingLocation` bridges them |
+| Click & Collect (CC) | ORDER::CC + FULFILMENT::CC share `CC` subtype |
+| Multi-Location (MULTI) | ORDER::MULTI — may share fulfilment with HD or have its own |
+| Article Management | ARTICLE::DEFAULT — shared infrastructure, used by HD and CC |
+| Wave Management | WAVE::DEFAULT — shared infrastructure for warehouse operations |
+| Sourcing | No dedicated workflow — `CustomSourceOrder` runs within ORDER flows |
+| Shipping Integration | `CalculateShippingCost` + `NotifyCustomerViaWebhook` + webhook settings |
+
+**Phase 3 for "Home Delivery" would produce:**
+
+```
+ORDER::HD                    FULFILMENT::HD              ARTICLE
+────────────                 ──────────────              ───────
+CREATED
+  │ CustomSourceOrder
+BOOKED
+  │ CreateFulfilmentFromSL
+  │──────────────────────────> CREATED
+                               │ AllocateArticles
+                               │─────────────────────────> CREATED
+                                                           │ AssignLocation
+                                                         ACTIVE
+                                                           │ PickArticle
+                                                         PICKED
+                                                           │─────────────────> ArticleComplete
+                               FULFILLED ◄───────────────
+                               │ CalculateShippingCost
+                               │ NotifyCustomerViaWebhook
+                             COMPLETE
+  │ AutoCompleteOrder ◄──────
+COMPLETE
+```
+
+---
+
+## Build Steps
+
+To implement this skill:
+
+1. **Create the skill directory:**
+   ```
+   fluent-ai-skills/content/dev/skills/fluent-implementation-map/SKILL.md
+   ```
+
+2. **Write the SKILL.md** using this design doc as the specification. Key sections:
+   - Frontmatter (name, description, allowed-tools, argument-hint)
+   - Purpose & When to Use
+   - No Planning Gate (read-only)
+   - Inputs table
+   - Phase 1-5 detailed instructions (adapt from this doc)
+   - Output format with worked examples
+   - Graceful degradation for missing MCP
+   - Handoff Protocol
+   - Error Reporting
+   - Session Tracking
+
+3. **Register in metadata.json:**
+   ```json
+   "fluent-implementation-map"  // add to dev.skills and dev.commands arrays
+   ```
+
+4. **Update fluent-dev agent** trigger list with new keywords.
+
+5. **Update README.md** capabilities table with new row.
+
+6. **Update CHANGELOG.md** `[Unreleased]` section.
+
+7. **Run tests:**
+   ```bash
+   cd fluent-ai-skills && npm test
+   ```
+
+8. **Reinstall all targets:**
+   ```bash
+   node bin/cli.mjs install --target claude
+   node bin/cli.mjs install --target cursor
+   # ... etc
+   ```
+
+9. **Test against live account:**
+   ```
+   /fluent-implementation-map --profile SAGIRISH --retailer "Module Test"
+   ```
+
+## Machine-Readable Output (`inventory.json`)
+
+The `inventory.json` file provides a structured output for downstream tooling:
+
+```json
+{
+  "generated": "2026-02-25T14:30:00Z",
+  "profile": "HMDEV",
+  "retailer": "HM_TEST",
+  "features": [
+    {
+      "slug": "home-delivery",
+      "confidence": "HIGH",
+      "clusterMethod": "subtype-family + event-chain",
+      "category": "Business Feature",
+      "customisationScore": 3,
+      "workflows": ["ORDER::HD", "FULFILMENT::HD_WH", "ARTICLE::HD"],
+      "primaryEntity": "ORDER::HD",
+      "entryEvents": ["CreateOrder"],
+      "terminalStatuses": ["COMPLETE", "CANCELLED"],
+      "crossEntityEvents": ["CreateFulfilment", "FulfilmentComplete"],
+      "ruleCount": { "custom": 12, "ootb": 34 },
+      "settingsReferenced": ["WEBHOOK_ENDPOINT_ORDER_BOOK", "INVENTORY_STRATEGY"],
+      "webhooks": ["NotifyWarehouse"],
+      "scheduledEvents": ["RetryAllocation"]
+    }
+  ],
+  "unclustered": [
+    { "workflow": "VIRTUAL_CATALOGUE::DEFAULT", "reason": "Standalone entity, no event connections" }
+  ],
+  "crossFeatureConnections": [
+    { "from": "home-delivery", "to": "inventory-management", "via": "UpdateInventory", "direction": "outbound" }
+  ]
+}
+```
+
+---
+
+## Feature Stub Creation (`--create-stubs`)
+
+When `--create-stubs` is passed, create `features/<slug>/status.json` for each discovered feature:
+
+```json
+{
+  "$schema": "feature-status-v1",
+  "feature": "home-delivery",
+  "retailers": ["HM_TEST"],
+  "status": "DISCOVERY",
+  "created": "2026-02-25",
+  "updated": "2026-02-25",
+  "spec": null,
+  "plan": null,
+  "planRevision": null,
+  "architecture": false,
+  "basedOn": null,
+  "next": "/fluent-feature-explain",
+  "sessions": [],
+  "_discoveredBy": "/fluent-implementation-map",
+  "_workflows": ["ORDER::HD", "FULFILMENT::HD_WH", "ARTICLE::HD"],
+  "_confidence": "HIGH"
+}
+```
+
+The `_discoveredBy`, `_workflows`, and `_confidence` fields are prefixed with `_` to indicate discovery metadata (not part of the standard schema). Downstream skills like `/fluent-feature-explain` can read `_workflows` to know which workflows to analyze without asking the user.
+
+**Lifecycle bridge:** After running with `--create-stubs`, the user can:
+- Run `/fluent-feature-status` to see all discovered features
+- Run `/fluent-feature-explain <slug>` on any feature (reads `_workflows` from status.json)
+- Start the planning chain on any feature via `/fluent-use-case-discover`
+
+---
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| Account with 0 workflows | Report "No workflows found" with guidance to deploy |
+| Account with 1 workflow | Single-feature output (no clustering needed) |
+| All workflows same entity type | Cluster by subtype only; if same subtype, treat as single feature |
+| Workflow with no subtype (e.g., `ORDER::ORDER`) | Use Heuristic 3 (naming patterns) or mark as UNCLUSTERED |
+| 50+ workflows | Paginate output; recommend `--depth summary` + `--focus` filter |
+| No custom rules (pure OOTB) | Still valid; report rule counts as 0/N; customisation score = 0 |
+| No SOURCE/ directory | Skip code analysis; note in gap analysis |
+| Circular event chains | Detect and flag as cross-feature loops (not errors) |
+| Multiple retailers sharing workflows | Analyze per-retailer; note shared patterns |
+
+---
+
+## Estimated Token Budget
+
+| Phase | Summary depth | Detailed (per feature) |
+|-------|---------------|------------------------|
+| Phase 1: Inventory collection | ~3k (workflow list + plugin.list + env.discover) | Same |
+| Phase 2: Feature identification | ~1k + 2k per workflow (parse JSON) | Same |
+| Phase 3: Flow mapping | ~2k per feature (summary tables) | ~8-15k (full architecture) |
+| Phase 4: Gap analysis | ~1k | Same |
+| Phase 5: Report generation | ~3k | ~5k |
+| **Total (10 workflows, 3 features)** | **~30k tokens** | **~70k tokens** |
+
+---
+
+## Open Questions (Resolved)
+
+1. **Should `--depth detailed` auto-invoke `/fluent-feature-explain`?** → **No.** Use the same analysis patterns inline but link to `/fluent-feature-explain --feature <slug>` for deeper drill-down. Keeps the skill self-contained without subprocess coordination.
+
+2. **Should the skill create `features/<slug>/` directories?** → **Yes, but opt-in via `--create-stubs`.** Not by default. This bridges discovery into the feature lifecycle without forcing it. See "Feature Stub Creation" section above.
+
+3. **How to handle accounts with 50+ workflows?** → **Use `--focus` filter + `--depth summary` as default.** Edge cases table covers pagination guidance. Progressive output: emit features as they're identified.
+
+4. **Should it diff against a previous map?** → **v2 feature.** Not in initial implementation. The `inventory.json` output enables external diffing.
+
+5. **Naming** → **Resolved: `/fluent-implementation-map`.** Already registered in metadata.json, CHANGELOG, README. Name emphasises the output (a map of the implementation).