@fluentcommerce/ai-skills 0.13.0 → 0.15.0

package/docs/02-prompt-guide.md

@@ -0,0 +1,246 @@
+# Prompt Guide — Navigating 60+ Skills
+
+> You have 60+ skills. You don't need to learn them all.
+> This guide organizes them into a progressive path: start with 5, expand as your work demands.
+
+> [!TIP]
+> **First time?** Start with [first-session.md](01-first-session.md) — a 20-minute guided walkthrough.
+> **Need full examples?** See [Setup Reference & Troubleshooting](05-getting-started.md).
+> **This doc** answers: "which skills exist, what do they do, and what should I type?"
+
+---
+
+## How Prompting Works
+
+You describe what you want in plain English. The AI picks the right skill. You don't need to name skills — but you can use `/slash-commands` if you know them.
+
+The AI **always asks before changing anything**. You'll see a plan and say `"approved"` before any files are created or anything is deployed.
+
+---
+
+## Level 1 — Your First Session (5 skills)
+
+Safe, read-only, instant value. Nothing is changed or created.
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-connect` | Links workspace to your Fluent account | `/fluent-connect --profile MY_PROFILE` |
+| `fluent-account-snapshot` | Shows what's deployed — workflows, modules, retailers | `"What's deployed on this account?"` |
+| `fluent-feature-explain` | Explains a feature with diagrams and rule inventory | `"Explain how Home Delivery works end-to-end"` |
+| `fluent-trace` | Investigates stuck orders with event timeline and root cause | `"Why is order HD-001 stuck in BOOKED?"` |
+| `fluent-workspace-tree` | Shows annotated directory layout | `"Show me the workspace tree"` |
+
+**After this level:** You understand the account, can explain features, and can investigate issues.
+
+---
+
+## Quick Reference — Common Prompt Chains
+
+These are the most common end-to-end workflows. Each row is a complete prompt chain you can follow in order.
+
+| I'm building... | Prompt chain (say these in order) | Skills that trigger | What you get |
+|-----------------|----------------------------------|---------------------|-------------|
+| **A new feature (end-to-end)** | "I need to handle return orders" → "Plan the return order feature" → "Approved" → "Build the workflow" → "Scaffold the module" → "Deploy to staging" → "Run E2E test" | `use-case-discover` → `feature-plan` → `workflow-builder` → `module-scaffold` → `workflow-deploy` + `module-deploy` → `e2e-test` | `spec.md`, `plan.md`, workflow JSON, Java classes, module ZIP, test results |
+| **A new workflow** | "Build an ORDER::RETURN workflow" → review plan → "Approved" → "Deploy to staging" | `workflow-builder` → `workflow-deploy` | Workflow JSON in `accounts/<PROFILE>/workflows/` |
+| **A new rule + tests** | "Create a rule called ValidateReturnWindow" → "Generate tests for it" → "Build the module" | `rule-scaffold` → `rule-test` → `build` | Java class, JUnit test, module ZIP |
+| **A UI page** | "Add a returns page to the order manifest" → "Preview it" → "Deploy the manifest" | `mystique-builder` → `mystique-preview` → `settings` | Manifest JSON in `accounts/<PROFILE>/manifests/` |
+| **Debug a stuck order** | "Why is order HD-001 stuck in BOOKED?" → "Show the event timeline" → "Compare runtime vs workflow" | `trace` → `entity-flow-diagnose` | Timeline, root-cause report |
+| **Understand what's deployed** | "What's deployed on this account?" → "Explain how Home Delivery works" → "Map the entire implementation" | `account-snapshot` → `feature-explain` → `implementation-map` | Account summary, feature diagrams, implementation inventory |
+| **Go-live readiness** | "Run pre-deploy checks" → "Run a Ready For Launch assessment" | `pre-deploy-check` → `rfl-assess` | GO/NO-GO report, RFL assessment |
+
+All artifacts land under `accounts/<PROFILE>/` in your workspace.
+
+---
+
+## Level 2 — Your First Week (add 12 skills)
+
+These create or change things — the AI presents a plan and waits for your approval first.
+
+### Understand and Plan
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-use-case-discover` | Gathers requirements through interactive prompts | `"I need to handle return orders"` |
+| `fluent-feature-plan` | Creates an 18-section implementation plan with diagrams | `"Plan the return order feature"` |
+| `fluent-implementation-map` | Maps what's already been built across the workspace | `"Map the entire implementation"` |
+
+### Build
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-workflow-builder` | Creates workflow JSON with statuses, rulesets, and triggers | `"Build an ORDER::RETURN workflow"` |
+| `fluent-rule-scaffold` | Scaffolds Java rule classes with annotations and tests | `"Create a rule called ValidateReturnWindow"` |
+| `fluent-rule-test` | Generates or repairs JUnit 5 tests for existing rules | `"Generate tests for ValidateReturnWindow"` |
+| `fluent-module-scaffold` | Creates Maven project skeleton with pom.xml and module.json | `"Scaffold a module for returns"` |
+| `fluent-build` | Compiles and packages a module into a deployable ZIP | `"Build the returns module"` |
+
+### Deploy and Verify
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-pre-deploy-check` | Runs 37 quality gates across 9 phases — produces GO/NO-GO report | `"Run pre-deploy checks"` |
+| `fluent-workflow-deploy` | Uploads workflow JSON to target environment | `"Deploy ORDER::RETURN to staging"` |
+| `fluent-module-deploy` | Deploys compiled module to target environment | `"Deploy the returns module to staging"` |
+| `fluent-e2e-test` | Runs end-to-end test with event firing and assertions | `"Run E2E test of the return flow"` |
+
+**After this level:** You can plan, build, deploy, and verify features. For prerequisites and troubleshooting, see [Setup Reference](05-getting-started.md).
+
+---
+
+## How Routing Works
+
+You don't need to know this — the AI picks the right agent automatically. But if you're curious:
+
+| Agent | Handles | Example prompts |
+|-------|---------|----------------|
+| `fluent-dev` | Cross-cutting: planning, mapping, status, E2E | "Plan the return feature", "What features are in progress?" |
+| `fluent-backend-dev` | Workflows, rules, modules, events, Java, deploy | "Build a workflow", "Create a rule", "Trace this event" |
+| `fluent-frontend-dev` | Manifests, pages, SDK components, UI testing | "Add a page to the manifest", "Scaffold a component" |
+| `fluent-cli` | CLI profiles, retailers, account setup | "Create a profile", "List retailers" |
+| `fluent-mcp` | MCP servers, GraphQL, events, batch ops | "Send a test event", "Query orders via GraphQL" |
+| `fluent-rfl` | Production readiness audits | "Run an RFL assessment" |
+
+---
+
+## Skills by Lifecycle Stage
+
+If you're following a structured development process:
+
+| Stage | What you're doing | Key skills |
+|-------|------------------|-----------|
+| **Setup** | Connect workspace, configure profiles | `fluent-connect`, `fluent-bootstrap`, `fluent-profile` |
+| **Discover** | Understand what exists | `fluent-account-snapshot`, `fluent-feature-explain`, `fluent-implementation-map` |
+| **Requirements** | Define what to build | `fluent-use-case-discover` |
+| **Plan** | Design the solution | `fluent-feature-plan`, `fluent-scope-plan` |
+| **Build (backend)** | Workflows, rules, modules | `fluent-workflow-builder`, `fluent-rule-scaffold`, `fluent-module-scaffold` |
+| **Build (frontend)** | Manifests, components | `fluent-mystique-builder`, `fluent-mystique-scaffold` |
+| **Validate** | Quality gates | `fluent-pre-deploy-check`, `fluent-module-validate`, `fluent-mystique-assess` |
+| **Deploy** | Push to environment | `fluent-workflow-deploy`, `fluent-module-deploy` |
+| **Test** | Verify behavior | `fluent-e2e-test`, `fluent-ui-test`, `fluent-test-data` |
+| **Diagnose** | Debug failures | `fluent-trace`, `fluent-entity-flow-diagnose`, `fluent-rollback` |
+
+---
+
+## Level 3 — All Skills by Category
+
+Pick what's relevant to your work. Each table is independent — skip categories you don't need.
+
+### Backend: Workflows
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-workflow-analyzer` | Static analysis — orphaned rulesets, trigger conflicts, schema validation | `"Analyze the HD workflow for issues"` |
+| `fluent-workflow` | CLI workflow operations — list, download, compare | `"Download all workflows for MY_RETAILER"` |
+| `fluent-transition-api` | Entity status transitions and allowed actions | `"What transitions are available for ORDER?"` |
+
+### Backend: Rules and Modules
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-custom-code` | Analyzes existing Java rules — explains logic, annotations | `"Explain what SendEventForArticles does"` |
+| `fluent-rule-lookup` | Finds rules by name, annotation, or behavior across deployed modules | `"Find all rules that use @ParamString 'eventName'"` |
+| `fluent-module-validate` | Validates module structure, registrations, dependencies | `"Validate the returns module"` |
+| `fluent-entity-flow-diagnose` | Traces entity flow across multiple workflows | `"Trace the fulfilment lifecycle for HD"` |
+| `fluent-module-convert` | Onboards existing source code into a proper module | `"Onboard this legacy code into a module"` |
+| `fluent-data-module-scaffold` | Creates data-only modules (no Java, just config) | `"Create a data module for reference data"` |
+
+### Frontend: Mystique UI
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-mystique-builder` | Builds or modifies manifest JSON pages | `"Add a returns page to the order manifest"` |
+| `fluent-mystique-scaffold` | Creates new manifest project from scratch | `"Scaffold a manifest for my-returns"` |
+| `fluent-mystique-component` | Scaffolds custom SDK component projects | `"Create a ReturnReasonPicker component"` |
+| `fluent-mystique-assess` | Analyzes and validates manifest structure and correctness | `"Analyze and validate the order manifest"` |
+| `fluent-mystique-diff` | Compares manifest versions | `"Diff the manifest against staging"` |
+| `fluent-mystique-sdk-reference` | SDK API and pattern reference | `"How do I use the fc-table component?"` |
+| `fluent-mystique-preview` | Preview manifest rendering | `"Preview what the returns page looks like"` |
+| `fluent-frontend-build` | Builds frontend artifacts | `"Build the manifest for deployment"` |
+| `fluent-frontend-review` | Reviews frontend code quality | `"Review the returns manifest"` |
+| `fluent-frontend-readme` | Generates frontend documentation | `"Generate README for the manifest project"` |
+| `fluent-ui-test` | UI testing with assertions | `"Test the order detail page"` |
+| `fluent-ui-record` | Records UI interactions for test replay | `"Record a test for the returns form"` |
+
+### Operations and CLI
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-profile` | Manage CLI profiles — create, switch, list | `"Show available profiles"` |
+| `fluent-bootstrap` | Set up new accounts from scratch | `"Bootstrap a new test account"` |
+| `fluent-settings` | Query and manage platform settings | `"Audit settings for ORDER::HD"` |
+| `fluent-retailer-config` | Retailer and location configuration | `"Show retailer configuration"` |
+| `fluent-cli-retailer` | CLI retailer operations | `"List retailers on this account"` |
+| `fluent-connection-analysis` | Check connector and webhook health | `"Are all connectors working?"` |
+| `fluent-rollback` | Roll back a failed deployment | `"Roll back ORDER::HD to previous version"` |
+
+### Monitoring, Events, and Quality
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-system-monitoring` | Event processing metrics from Prometheus | `"Show event failure rates"` |
+| `fluent-event-api` | Send and inspect events | `"Send a test event to order HD-001"` |
+| `fluent-rfl-assess` | Ready For Launch production readiness audit | `"Run a Ready For Launch assessment"` |
+| `fluent-job-batch` | Batch data ingestion jobs | `"Batch ingest inventory from CSV"` |
+| `fluent-test-data` | Generate test data and fixtures | `"Create test orders for the HD flow"` |
+
+### Data and Sourcing
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-sourcing` | Responsive Sourcing Framework reference — profiles, strategies, scoring | `"How does sourcing work for HD fulfilment?"` |
+| `fluent-inventory-catalog` | Inventory and catalog setup | `"Set up inventory for Click & Collect"` |
+| `fluent-knowledge-init` | Initialize workspace knowledge docs | `"Set up knowledge docs for this workspace"` |
+
+### Feature Lifecycle and Tracking
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-feature-status` | Check feature progress across workspace | `"What features are in progress?"` |
+| `fluent-scope-plan` | Phases and scope decomposition for large features | `"Decompose the returns spec into phases"` |
+| `fluent-goal` | Goal-oriented task tracking with deadlines | `"My goal is to ship returns by Friday"` |
+| `fluent-session` | Session tracking and resume across conversations | `"What did we do in the last session?"` |
+| `fluent-archive` | Archive completed features | `"Archive the returns feature"` |
+| `fluent-skill-observability` | Skill tracing, routing reports, and feedback | `"Which skill handled my last prompt?"` |
+
+### MCP and Reference
+
+| Skill | What it does | Try this |
+|-------|-------------|----------|
+| `fluent-mcp-tools` | MCP extension tool reference (55+ tools) | `"What MCP tools are available for events?"` |
+| `fluent-mcp-core` | Official CLI MCP server reference | `"How do I use the official MCP server?"` |
+| `fluent-cli-reference` | CLI command reference and skill index | `"Show me the CLI command for workflow download"` |
+| `fluent-cli-mcp-cicd` | MCP and CI/CD pipeline setup | `"Set up MCP for CI/CD"` |
+
+---
+
+## Tips for Effective Prompting
+
+**Be specific about what you want, not which skill to use:**
+- Good: `"Why is order HD-001 stuck in BOOKED?"`
+- Less useful: `"Run the trace skill"`
+
+**Chain prompts to go deeper:**
+```
+"Explain how Home Delivery works"           ← start broad
+"What rules handle the BOOKED status?"      ← zoom in
+"Show me the code for SendEventForArticles" ← inspect
+"Are there tests for that rule?"            ← verify
+```
+
+**Use the approval gate — it's your safety net:**
+- When the AI shows a plan, ask questions before approving
+- `"What are the risks?"` or `"Change the workflow name to X"` before `"approved"`
+
+**Resume across sessions:**
+- `"Continue working on return orders"` — the AI reads `status.json` and picks up where you left off
+
+---
+
+## How This Relates to Other Docs
+
+| Doc | Purpose | When to use it |
+|-----|---------|---------------|
+| **This guide** | Which skills exist, what to type, routing, and lifecycle | When you're wondering "can AI do X?" |
+| [first-session.md](01-first-session.md) | 20-minute guided first session | Your very first time |
+| [Setup Reference](05-getting-started.md) | Prerequisites, workspace layout, troubleshooting | When you need setup details or hit errors |
+| [use-cases.md](03-use-cases.md) | 21 detailed scenario walkthroughs | When you need a specific scenario end-to-end |