@fluentcommerce/ai-skills 0.2.0 → 0.3.0

package/content/dev/skills/fluent-feature-plan/SKILL.md

@@ -1,221 +1,478 @@
----
-name: fluent-feature-plan
-description: Produce comprehensive feature implementation plans with universal NEW/EXISTING/MODIFIED/REUSED/OOTB classification across all artifacts. Covers rules, workflows, settings, webhooks, GraphQL operations, cross-entity flows, and deployment. Triggers on "plan feature", "feature plan", "plan implementation", "design feature", "plan this feature", "what do I need to build".
-user-invocable: true
-allowed-tools: Bash, Read, Write, Edit, Glob, Grep
-argument-hint: <feature-description> [--profile PROFILE] [--retailer RETAILER_REF]
----
-
-# Feature Planner
-
-Produce comprehensive, self-contained implementation plans for Fluent Commerce features. A "feature" spans multiple artifacts — rules, workflow rulesets, settings, webhooks, entity types, and deployments. The plan is the contract — an implementer can write code from it without ambiguity.
-
-**This skill is the MANDATORY entry point for any multi-artifact Fluent implementation work.** All downstream implementation skills (`/fluent-rule-scaffold`, `/fluent-workflow-builder`, `/fluent-settings`, `/fluent-build`, `/fluent-module-deploy`) require an approved plan from this skill before they proceed. Each implementation skill has a Pre-flight: Plan Verification step that checks `accounts/<PROFILE>/plans/` for an approved plan. If no plan exists and the work is multi-artifact, those skills will redirect back here.
-
-**Do NOT use IDE-native plan mechanisms** (e.g., Claude Code's `EnterPlanMode`, Cursor's plan mode) as a substitute for this skill. Those mechanisms write to ephemeral locations that are lost between sessions and do not follow the structured 18-section template.
-
-## Template Reference
-
-**The full plan template with worked examples and section applicability guide lives at: `PLAN_TEMPLATE.md` (in this skill directory).**
-
-Read that file before producing any plan. It defines:
-- The 18-section structure with TOC (including §6.1 Complete Workflow Inventory and §3.6 Workflow Processing Flow)
-- Universal Source classification (NEW / EXISTING / MODIFIED / REUSED / OOTB)
-- Section applicability guide (which sections are required vs optional)
-- Rules classification decision flow
-- Diagram requirements (Mermaid stateDiagram-v2, sequenceDiagram, flowchart)
-- Plan lifecycle (PENDING → APPROVED → implementation)
-
-## When to Use
-
-Use `/fluent-feature-plan` when the work involves **multiple artifacts**:
-- A new capability needing workflow changes + new rules + settings + possibly webhooks
-- A change spanning multiple entity types (ORDER → FULFILMENT → LOCATION)
-- Any implementation request where the scope isn't covered by a single skill
-
-**If requirements are unclear**, run `/fluent-use-case-discover` first to produce a structured Business Spec. The spec feeds directly into this skill with section-to-section mapping.
-
-**For single-artifact work**, the individual skill's Planning Gate is sufficient:
-- Single new rule → `/fluent-rule-scaffold` Planning Gate
-- Single workflow edit → `/fluent-workflow-builder` Planning Gate
-- Settings-only change → `/fluent-settings` Planning Gate
-- Retrospective feature documentation → `/fluent-feature-explain`
-- Scope document decomposition → `/fluent-scope-decompose`
-
-## Phase 1: Discovery
-
-Before writing a plan, gather evidence to classify every artifact.
-
-### 1.1 OOTB Rule Search
-
-```
-plugin.list name="<keyword>"     # e.g., "Fulfilment", "Pickup", "Webhook"
-plugin.list name="SendEvent"     # standard event forwarding rules
-plugin.list compact=true         # full inventory (compact payload)
-```
-
-Determine which parts of the feature can use OOTB rules vs. need custom. For every rule the feature needs, try to find an OOTB match FIRST.
-
-### 1.2 Existing Workflows
-
-```bash
-# Check what's deployed
-fluent workflow list -p <PROFILE> -r <RETAILER_REF>
-# Download if not local
-fluent workflow download -p <PROFILE> -r <RETAILER_REF> -w all -o accounts/<PROFILE>/workflows/<RETAILER_REF>/
-```
-
-Read workflow JSONs to map existing statuses, rulesets, and triggers. Identify which workflows need modification and their current versions.
-
-**For §6.1 Complete Workflow Inventory:** Parse each modified workflow's JSON to extract the complete ruleset list — entity type, subtype, trigger event, trigger status, and rule names. This feeds directly into the §6.1 table and §3.6 Workflow Processing Flow diagram. Don't rely on the implementer to manually enumerate rulesets.
-
-### 1.3 Existing Settings
-
-```bash
-# Via MCP
-graphql.query: settings(first: 100) filtered by name pattern
-# Or via CLI
-fluent setting list -p <PROFILE> -r <RETAILER_REF> -n "*keyword*"
-```
-
-Find settings that already exist vs. need creation.
-
-### 1.4 Local Source Analysis
-
-Search `accounts/<PROFILE>/SOURCE/` for:
-- `module.json` — rule registrations
-- `source-map.json` — if `/fluent-custom-code` was run
-- `behavior-map.md` — rule behavior descriptions
-- Existing Java rule classes for reusable patterns
-
-### 1.5 Module Identification
-
-Identify the target module for new custom rules:
-- Search `accounts/<PROFILE>/SOURCE/` for existing modules
-- If no module exists, flag `/fluent-module-scaffold` as a prerequisite task
-
-## Phase 2: Classification
-
-For EVERY artifact the feature touches, apply one of these labels:
-
-| Label | Meaning | Required Detail in Plan |
-|-------|---------|------------------------|
-| **NEW** | Doesn't exist yet, must be created | Full pseudo logic / value shape / trigger spec |
-| **EXISTING** | Already deployed, no modification needed | State current value, confirm no change |
-| **MODIFIED** | Already exists but needs changes | Show before → after diff |
-| **REUSED** | Pattern exists in codebase, copy the approach | Reference source file/rule |
-| **OOTB** | Platform rule, use with configuration only | State which props/values to configure |
-
-This applies universally across ALL plan sections — rules, rulesets, statuses, settings, webhooks, GraphQL operations, cross-entity impacts, files.
-
-## Phase 3: Pseudo Logic for NEW Rules
-
-For every **NEW** rule, write pseudo logic that is:
-- **Unambiguous** — a developer can implement from it without asking questions
-- **Shows data flow**: READ → VALIDATE → QUERY → BUILD → MUTATE → LOG
-- **Shows branching**: IF/ELSE with error paths and thrown exceptions
-- **References specific APIs**: `DynamicUtils.queryList()`, `SettingUtils.getSettingByRef()`, `JsonUtils.getJsonPath()`
-- **Stays at design level** — NOT Java code, but precise enough to translate directly
-
-```
-FUNCTION run(context):
-    order = context.getEntity()
-    event = context.getEvent()
-
-    // 1. Extract required fields
-    pickupLocationRef = extractFromPath(event, props.pickupLocationPath)
-    IF pickupLocationRef IS NULL:
-        THROW "Pickup location ref required but null at path: {pickupLocationPath}"
-
-    // 2. Fetch order items
-    items = DynamicUtils.queryList(context, "items", OrderItem.class, null)
-    IF items IS EMPTY:
-        THROW "Order has no items — cannot create fulfilment"
-
-    // 3. Read config from setting
-    config = SettingUtils.getSettingByRef(context, props.configSettingName)
-    maxPickupHours = config.lobValue.maxPickupHours
-
-    // 4. Validate
-    IF requestedPickupTime > order.createdOn + maxPickupHours hours:
-        THROW "Pickup window expired"
-
-    // 5. Build and mutate
-    fulfilmentRef = "CURB-{order.ref}-{pickupLocationRef}"
-    DynamicUtils.create(context, CreateFulfilmentInput { ref, type, items, attributes })
-
-    // 6. Log
-    context.addLog("Created curbside fulfilment {fulfilmentRef}")
-```
-
-**For OOTB rules**: just state the configuration props to set in the ruleset — no pseudo logic needed.
-
-**For EXISTING rules**: confirm "no code changes" or describe the modification.
-
-## Phase 4: Plan Writing
-
-**Write to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-feature-plan-<slug>.md`
-
-Follow the 18-section template from `PLAN_TEMPLATE.md` (sibling file). Validate all Mermaid diagram blocks per `/fluent-mermaid-validate` before writing the plan file. Key per-section notes:
-
-| Section | Source-Column Required | Key Content |
-|---------|----------------------|-------------|
-| §4 Workflows | Yes (NEW/EXISTING/MODIFIED) | Workflow name, current version, action |
-| §5 Statuses | Yes | Status, entity type, which ruleset adds it |
-| §6 Rulesets | Yes | Trigger event, from/to status, ordered rule list with source annotations |
-| §6.1 Complete Workflow Inventory | Yes (when modifying) | ALL rulesets in each modified workflow with NEW/EXISTING/MODIFIED annotations |
-| §3.6 Workflow Processing Flow | Yes (when modifying) | Flowchart: complete status→ruleset→status chain, NEW/MODIFIED highlighted |
-| §7 Rules Inventory | Yes | ALL rules for the feature with source + purpose |
-| §8 Detailed Design | For NEW rules only | Class, params table, pseudo logic, GraphQL ops |
-| §9 Settings | Yes | Context, contextId, value type, JSON example for NEW |
-| §10 Webhooks | Yes | Setting name, method, payload shape |
-| §11 Scheduled Events | Yes | Event name, delay, purpose |
-| §12 GraphQL Ops | Yes (NEW/REUSED) | Query/mutation, root field, selected paths |
-| §13 Cross-Entity | Yes | Source → target entity, mechanism |
-| §14 Files | Yes (NEW/MODIFIED) | All created/modified files |
-
-## Phase 5: Approval
-
-1. Set `Status: PENDING`, `Revision: 1`
-2. Present the full plan content to the user
-3. Wait for explicit approval before any implementation
-4. On approval: update `Status: APPROVED`, `Approved by: user`
-5. On rejection: increment `Revision`, revise, re-present
-6. On "just do it": write `Status: APPROVED (auto-skip)`, `Approved by: user (gate skipped)`, proceed
-
-## Phase 6: Handoff to Implementation Skills
-
-After approval, the plan becomes the source of truth. Each skill reads its relevant sections:
-
-| Artifact Type | Implementation Skill | Plan Sections |
-|--------------|---------------------|---------------|
-| New custom rules | `/fluent-rule-scaffold` | §7 Rules, §8 Detailed Design |
-| Workflow changes | `/fluent-workflow-builder` | §4 Workflows, §5 Statuses, §6 Rulesets |
-| Settings | `/fluent-settings` | §9 Settings |
-| Module build + deploy | `/fluent-build` → `/fluent-module-deploy` | §17 Deployment |
-| E2E verification | `/fluent-e2e-test` | §16 Test Plan |
-
-The deployment sequence in §17 defines execution order. Track tasks from §17 via TodoWrite.
-
-## Updating a Plan Mid-Implementation
-
-If discovery during implementation reveals missing artifacts:
-
-1. Edit the plan file in place — increment `Revision: N+1`
-2. Add a revision note at the bottom with what changed and why
-3. Re-present the changed sections for approval
-4. Continue from the updated plan
-
-## Cross-References
-
-| For | Use |
-|-----|-----|
-| Plan template structure & worked examples | `PLAN_TEMPLATE.md` (in this skill directory) |
-| OOTB rule search | `plugin.list` via MCP |
-| Workflow analysis | `/fluent-workflow-analyzer` |
-| Custom code analysis | `/fluent-custom-code` |
-| Connection topology | `/fluent-connection-analysis` |
-| Requirements gathering (before planning) | `/fluent-use-case-discover` |
-| Scope decomposition (from scope docs) | `/fluent-scope-decompose` |
-| Feature reverse-engineering (existing) | `/fluent-feature-explain` |
-| Module scaffolding (if needed) | `/fluent-module-scaffold` |
+---
+name: fluent-feature-plan
+description: Produce comprehensive feature implementation plans with universal NEW/EXISTING/MODIFIED/REUSED/OOTB classification across all artifacts. Covers rules, workflows, settings, webhooks, GraphQL operations, cross-entity flows, and deployment. Triggers on "plan feature", "feature plan", "plan implementation", "design feature", "plan this feature", "what do I need to build".
+user-invocable: true
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep
+argument-hint: <feature-description> [--profile PROFILE] [--retailer RETAILER_REF]
+---
+
+# Feature Planner
+
+Produce comprehensive, self-contained implementation plans for Fluent Commerce features. A "feature" spans multiple artifacts — rules, workflow rulesets, settings, webhooks, entity types, and deployments. The plan is the contract — an implementer can write code from it without ambiguity.
+
+**This skill is the MANDATORY entry point for any multi-artifact Fluent implementation work.** All downstream implementation skills (`/fluent-rule-scaffold`, `/fluent-workflow-builder`, `/fluent-settings`, `/fluent-build`, `/fluent-module-deploy`) require an approved plan from this skill before they proceed. Each implementation skill has a Pre-flight: Plan Verification step that checks `accounts/<PROFILE>/features/<slug>/status.json` for an approved plan. If no plan exists and the work is multi-artifact, those skills will redirect back here.
+
+**Do NOT use IDE-native plan mechanisms** (e.g., Claude Code's `EnterPlanMode`, Cursor's plan mode) as a substitute for this skill. Those mechanisms write to ephemeral locations that are lost between sessions and do not follow the structured 18-section template.
+
+## Template Reference
+
+**The full plan template with worked examples and section applicability guide lives at: `PLAN_TEMPLATE.md` (in this skill directory).**
+
+Read that file before producing any plan. It defines:
+- The 18-section structure with TOC (including §6.1 Complete Workflow Inventory and §3.6 Workflow Processing Flow)
+- Universal Source classification (NEW / EXISTING / MODIFIED / REUSED / OOTB)
+- Section applicability guide (which sections are required vs optional)
+- Rules classification decision flow
+- Diagram requirements (Mermaid stateDiagram-v2, sequenceDiagram, flowchart)
+- Plan lifecycle (PENDING → APPROVED → implementation)
+
+> **Mandatory validation:** Before writing any Mermaid diagram to the plan file, validate syntax via `/fluent-mermaid-validate`. Common pitfalls: missing `direction` in flowcharts, spaces in state names for `stateDiagram-v2`, unquoted special characters in labels. Invalid diagrams render as error blocks in markdown viewers.
+
+## When to Use
+
+Use `/fluent-feature-plan` when the work involves **multiple artifacts**:
+- A new capability needing workflow changes + new rules + settings + possibly webhooks
+- A change spanning multiple entity types (ORDER → FULFILMENT → LOCATION)
+- Any implementation request where the scope isn't covered by a single skill
+
+**For single-artifact work**, the individual skill's Planning Gate is sufficient:
+- Single new rule → `/fluent-rule-scaffold` Planning Gate
+- Single workflow edit → `/fluent-workflow-builder` Planning Gate
+- Settings-only change → `/fluent-settings` Planning Gate
+- Retrospective feature documentation → `/fluent-feature-explain`
+- Scope document decomposition → `/fluent-scope-decompose`
+
+## Progress
+
+Emit this block at each phase transition to show progress:
+
+```
+▸ /fluent-feature-plan [1/6]
+  ✓ Pre-flight checks       → Discovery & classification
+  ○ Rule inventory           ○ Pseudo logic (NEW rules)
+  ○ Write plan               ○ Present for approval
+```
+
+Update the block as each phase completes — mark completed phases with `✓`, the active phase with `→`, and remaining phases with `○`. Replace `[1/6]` with the current phase number.
+
+## Pre-flight: Requirements Verification (MANDATORY)
+
+**A Business Spec is MANDATORY before feature planning.** The agent MUST NOT judge whether requirements are "clear enough" to skip the spec — that decision belongs exclusively to the end user.
+
+### Step 1: Check for approved Business Spec
+
+```bash
+# Check feature directories for an approved spec
+ls accounts/<PROFILE>/features/*/spec.md
+# Or check status.json for spec approval state
+cat accounts/<PROFILE>/features/<slug>/status.json   # look for "spec": "APPROVED"
+```
+
+If an **APPROVED** spec exists that matches the requested feature (check `status.json` for `"spec": "APPROVED"`):
+- Read the spec file at `features/<slug>/spec.md`
+- Confirm it covers the feature scope
+- Check the spec's Completeness Score (Section 12 in the spec). If score < 75%, warn: *"Business Spec completeness is below 75%. Specs below this threshold may cause planning gaps. Run `/fluent-use-case-discover` Phase 10 gap analysis to resolve, or proceed with `--force`."*
+- Proceed to Phase 1 using the spec as primary input
+- Reference the spec file path in the plan's §1 Business Context
+
+### Step 2: No approved spec → BLOCKED
+
+If no approved spec exists at `features/<slug>/spec.md`:
+- **STOP.** Do not proceed to Phase 1.
+- Inform the user: *"No approved Business Spec found. A spec is required before feature planning. I recommend running `/fluent-use-case-discover` to produce a structured Business Spec first. If you want to skip the spec step and go straight to planning, say 'skip spec'."*
+- **IMPORTANT:** Always recommend the spec path. Present it as the default. The skip option is mentioned so the user knows it's available, but the recommendation is always to write the spec.
+- Invoke `/fluent-use-case-discover` to produce a spec
+- Resume `/fluent-feature-plan` only after the spec is **APPROVED**
+- Resume command: `/fluent-feature-plan --feature <slug>`
+
+### User override (explicit only)
+
+The user can bypass this check ONLY by explicitly saying: "skip spec", "skip use case", "go straight to plan", or similar **clear, unambiguous instruction**. The agent must NEVER infer a skip from vague statements or from judging that requirements "look structured enough".
+
+When the user explicitly overrides:
+1. Log `Pre-flight: Requirements Check SKIPPED (user override — no approved spec)` in the plan header
+2. Warn: *"Proceeding without a Business Spec. The plan may contain assumptions that require mid-implementation revision. Consider writing a spec after the plan if gaps emerge."*
+3. Proceed to Phase 1
+
+**What does NOT count as a user override:**
+- The user providing a one-sentence feature description
+- The user listing some requirements conversationally
+- The user saying "this is straightforward" or "it's simple"
+- The agent deciding the request is "clear enough"
+
+Only an **explicit instruction to skip** the spec step counts.
+
+## Slug Resolution
+
+If the feature directory doesn't exist yet, use the slug auto-suggestion protocol from `/fluent-use-case-discover`. The slug should have been established during spec creation; if not, apply the same rules here:
+1. Derive from feature/spec title → kebab-case → max 4 words → no dates → no skill prefixes
+2. Remove filler words (the, a, an, for, with, and)
+3. Check if `accounts/<PROFILE>/features/<slug>/` already exists
+4. If exists, reuse the existing slug
+5. If new, present to user for confirmation before creating directory
+
+### Decision summary
+
+```
+User requests feature
+        │
+        ▼
+┌───────────────────────────┐
+│ 1. Approved spec in       │──YES──▶ Proceed to Phase 1
+│    features/<slug>/       │
+│    spec.md?               │
+├───────────────────────────┤
+│ 2. No spec exists         │──────▶ BLOCKED
+│                           │        Recommend: /fluent-use-case-discover
+│                           │        Mention skip option to user
+├───────────────────────────┤
+│ 3. User explicitly says   │──YES──▶ Proceed to Phase 1 (log override + warn)
+│    "skip spec"?           │
+└───────────────────────────┘
+
+NEVER auto-proceed without a spec. NEVER judge requirements as "sufficient".
+The decision to skip belongs to the end user, not the agent.
+```
+
+## Handoff Protocol
+
+### Mandatory approval gate before implementation
+
+After writing the plan to `features/<slug>/plan.md`, the agent MUST:
+1. Present the plan to the user for review
+2. **STOP and WAIT** for explicit user approval ("approved", "go ahead", "looks good", "do it")
+3. Only after user approval: update `status.json` to `plan: "APPROVED"` and emit `-> NEXT`
+4. If the user asks questions or requests changes → answer/apply changes, keep waiting for approval
+5. **NEVER auto-advance to implementation skills** — the approval gate is mandatory
+
+### Signals emitted by this skill
+
+| Signal | Condition | Example |
+|--------|-----------|---------|
+| `-> REVIEW: <path>` | Plan written, awaiting user review | `-> REVIEW: accounts/HMDEV/features/curbside/plan.md` |
+| `-> READY: <path>` | Plan reviewed AND approved by user | `-> READY: accounts/HMDEV/features/curbside/plan.md` |
+| `-> NEXT: /fluent-<skill>` | First implementation skill from plan (only after READY) | `-> NEXT: /fluent-rule-scaffold` |
+| `-> BLOCKED: <reason>` | Requirements insufficient | `-> BLOCKED: PREREQ_MISSING — No approved spec. Run /fluent-use-case-discover` |
+
+### Human-Friendly Translation
+
+When presenting handoff signals to the user, translate agent jargon into plain language:
+
+| Raw Signal | User-Facing Translation |
+|------------|------------------------|
+| `-> NEXT: /fluent-rule-scaffold` | "Plan approved. Next step: scaffold the Java rules. Shall I proceed?" |
+| `-> BLOCKED: Module not found` | "I can't build the workflow yet — the Java module needs to be created first. Want me to scaffold it?" |
+| `-> READY: plan.md` | "The feature plan is ready for your review." |
+| `-> REVIEW: plan.md` | "I've written the implementation plan. Please review it and let me know if it looks good." |
+| `-> SKIP: No settings` | "No settings changes needed for this feature — moving on." |
+
+**Rule:** Raw `->` signals should NEVER be shown to the user verbatim. Always wrap them in a natural-language sentence. The signals exist for agent-to-agent coordination; the user sees the translated version.
+
+### Error codes
+
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| `PREREQ_MISSING` | No approved Business Spec (spec.md with status APPROVED) | Run `/fluent-use-case-discover` to produce a spec. Agent cannot bypass — only user can say "skip spec" |
+| `SPEC_REQUIRED` | Agent attempted to skip spec without user override | Inform user: spec is mandatory, recommend `/fluent-use-case-discover`, mention skip option |
+| `VALIDATION_FAILED` | Plan template structure invalid or incomplete | Fix the plan sections flagged as incomplete |
+| `USER_OVERRIDE` | User explicitly said "skip spec" | Logged in plan header; proceed with assumptions |
+| `APPROVAL_PENDING` | Plan written but not yet approved by user | Wait for user review and explicit approval before proceeding |
+
+## Plan Revision Handling
+
+When a user requests plan changes during implementation (feature status is `IN_PROGRESS`):
+
+### Triggering a revision
+
+If the user says "change the plan", "update the plan", or requests modifications to an approved plan:
+
+1. **Read current plan** at `features/<slug>/plan.md`
+2. **Save current version** as `features/<slug>/plan.v<N>.md` where N = current `planRevision`
+3. **Apply changes** to `plan.md`, marking revised sections with:
+   ```
+   > **REVISED in v<N+1>:** <summary of what changed and why>
+   ```
+4. **Update status.json:**
+   - `status`: `"PLANNING"` (regressed from IN_PROGRESS)
+   - `planRevision`: increment by 1
+   - `plan`: `"DRAFT"` (pending re-approval)
+5. **Present revised plan** to user for review
+6. **WAIT for re-approval** — same mandatory gate as initial plan approval
+7. After approval: `status` → `"APPROVED"`, `plan` → `"APPROVED"`
+
+### Impact assessment
+
+After a plan revision, the agent MUST assess impact on already-completed work:
+
+1. List which plan sections changed (§ numbers)
+2. Cross-reference against completed implementation:
+   - Scaffolded rules → check if rule logic, parameters, or entity types changed
+   - Modified workflows → check if rulesets, statuses, or transitions changed
+   - Created settings → check if keys, values, or scopes changed
+3. Present impact summary: "These sections changed: §7, §9. Scaffolded rule X may need updating because [reason]."
+4. Let the user decide which completed artifacts to update — do NOT automatically modify scaffolded code
+
+### Revision history
+
+All plan versions are preserved in the feature directory:
+```
+features/<slug>/
+├── plan.md          ← current (latest) version
+├── plan.v1.md       ← original approved version
+├── plan.v2.md       ← first revision
+└── status.json      ← planRevision: 3
+```
+
+## Phase 1: Discovery
+
+Before writing a plan, gather evidence to classify every artifact.
+
+### 1.1 OOTB Rule Search
+
+```
+plugin.list name="<keyword>"     # e.g., "Fulfilment", "Pickup", "Webhook"
+plugin.list name="SendEvent"     # standard event forwarding rules
+plugin.list compact=true         # full inventory (compact payload)
+```
+
+Determine which parts of the feature can use OOTB rules vs. need custom. For every rule the feature needs, try to find an OOTB match FIRST.
+
+### 1.2 Existing Workflows
+
+```bash
+# Check what's deployed
+fluent workflow list -p <PROFILE> -r <RETAILER_REF>
+# Download if not local
+fluent workflow download -p <PROFILE> -r <RETAILER_REF> -w all -o accounts/<PROFILE>/workflows/<RETAILER_REF>/
+```
+
+Read workflow JSONs to map existing statuses, rulesets, and triggers. Identify which workflows need modification and their current versions.
+
+**For §6.1 Complete Workflow Inventory:** Parse each modified workflow's JSON to extract the complete ruleset list — entity type, subtype, trigger event, trigger status, and rule names. This feeds directly into the §6.1 table and §3.6 Workflow Processing Flow diagram. Don't rely on the implementer to manually enumerate rulesets.
+
+### 1.3 Existing Settings
+
+```bash
+# Via MCP
+graphql.query: settings(first: 100) filtered by name pattern
+# Or via CLI
+fluent setting list -p <PROFILE> -r <RETAILER_REF> -n "*keyword*"
+```
+
+Find settings that already exist vs. need creation.
+
+### 1.4 Local Source Analysis
+
+Search `accounts/<PROFILE>/SOURCE/` for:
+- `module.json` — rule registrations
+- `source-map.json` — if `/fluent-custom-code` was run
+- `behavior-map.md` — rule behavior descriptions
+- Existing Java rule classes for reusable patterns
+
+### 1.5 Module Identification
+
+Identify the target module for new custom rules:
+- Search `accounts/<PROFILE>/SOURCE/` for existing modules
+- If no module exists, flag `/fluent-module-scaffold` as a prerequisite task
+
+## Phase 2: Classification
+
+For EVERY artifact the feature touches, apply one of these labels:
+
+| Label | Meaning | Required Detail in Plan |
+|-------|---------|------------------------|
+| **NEW** | Doesn't exist yet, must be created | Full pseudo logic / value shape / trigger spec |
+| **EXISTING** | Already deployed, no modification needed | State current value, confirm no change |
+| **MODIFIED** | Already exists but needs changes | Show before → after diff |
+| **REUSED** | Pattern exists in codebase, copy the approach | Reference source file/rule |
+| **OOTB** | Platform rule, use with configuration only | State which props/values to configure |
+
+This applies universally across ALL plan sections — rules, rulesets, statuses, settings, webhooks, GraphQL operations, cross-entity impacts, files.
+
+## Phase 3: Pseudo Logic for NEW Rules
+
+For every **NEW** rule, write pseudo logic that is:
+- **Unambiguous** — a developer can implement from it without asking questions
+- **Shows data flow**: READ → VALIDATE → QUERY → BUILD → MUTATE → LOG
+- **Shows branching**: IF/ELSE with error paths and thrown exceptions
+- **References specific APIs**: `DynamicUtils.queryList()`, `SettingUtils.getSettingByRef()`, `JsonUtils.getJsonPath()`
+- **Stays at design level** — NOT Java code, but precise enough to translate directly
+
+```
+FUNCTION run(context):
+    order = context.getEntity()
+    event = context.getEvent()
+
+    // 1. Extract required fields
+    pickupLocationRef = extractFromPath(event, props.pickupLocationPath)
+    IF pickupLocationRef IS NULL:
+        THROW "Pickup location ref required but null at path: {pickupLocationPath}"
+
+    // 2. Fetch order items
+    items = DynamicUtils.queryList(context, "items", OrderItem.class, null)
+    IF items IS EMPTY:
+        THROW "Order has no items — cannot create fulfilment"
+
+    // 3. Read config from setting
+    config = SettingUtils.getSettingByRef(context, props.configSettingName)
+    maxPickupHours = config.lobValue.maxPickupHours
+
+    // 4. Validate
+    IF requestedPickupTime > order.createdOn + maxPickupHours hours:
+        THROW "Pickup window expired"
+
+    // 5. Build and mutate
+    fulfilmentRef = "CURB-{order.ref}-{pickupLocationRef}"
+    DynamicUtils.create(context, CreateFulfilmentInput { ref, type, items, attributes })
+
+    // 6. Log
+    context.addLog("Created curbside fulfilment {fulfilmentRef}")
+```
+
+**For OOTB rules**: just state the configuration props to set in the ruleset — no pseudo logic needed.
+
+**For EXISTING rules**: confirm "no code changes" or describe the modification.
+
+## Phase 4: Plan Writing
+
+**Write to:** `accounts/<PROFILE>/features/<slug>/plan.md`
+
+Follow the 18-section template from `PLAN_TEMPLATE.md` (sibling file). Validate all Mermaid diagram blocks per `/fluent-mermaid-validate` before writing the plan file. Key per-section notes:
+
+> **Diagram validation:** All Mermaid blocks must pass `/fluent-mermaid-validate` rules before writing to the plan file.
+
+| Section | Source-Column Required | Key Content |
+|---------|----------------------|-------------|
+| §4 Workflows | Yes (NEW/EXISTING/MODIFIED) | Workflow name, current version, action |
+| §5 Statuses | Yes | Status, entity type, which ruleset adds it |
+| §6 Rulesets | Yes | Trigger event, from/to status, ordered rule list with source annotations |
+| §6.1 Complete Workflow Inventory | Yes (when modifying) | ALL rulesets in each modified workflow with NEW/EXISTING/MODIFIED annotations |
+| §3.6 Workflow Processing Flow | Yes (when modifying) | Flowchart: complete status→ruleset→status chain, NEW/MODIFIED highlighted |
+| §7 Rules Inventory | Yes | ALL rules for the feature with source + purpose |
+| §8 Detailed Design | For NEW rules only | Class, params table, pseudo logic, GraphQL ops |
+| §9 Settings | Yes | Context, contextId, value type, JSON example for NEW |
+| §10 Webhooks | Yes | Setting name, method, payload shape |
+| §11 Scheduled Events | Yes | Event name, delay, purpose |
+| §12 GraphQL Ops | Yes (NEW/REUSED) | Query/mutation, root field, selected paths |
+| §13 Cross-Entity | Yes | Source → target entity, mechanism |
+| §14 Files | Yes (NEW/MODIFIED) | All created/modified files |
+
+## Phase 5: Approval
+
+1. Set `Status: PENDING`, `Revision: 1`
+2. Present the full plan content to the user
+3. Wait for explicit approval before any implementation
+4. On approval: update `Status: APPROVED`, `Approved by: user`
+5. On rejection: increment `Revision`, revise, re-present
+6. On "just do it": write `Status: APPROVED (auto-skip)`, `Approved by: user (gate skipped)`, proceed
+
+## Phase 6: Handoff to Implementation Skills
+
+After approval, the plan becomes the source of truth. Each skill reads its relevant sections:
+
+| Artifact Type | Implementation Skill | Plan Sections |
+|--------------|---------------------|---------------|
+| New custom rules | `/fluent-rule-scaffold` | §7 Rules, §8 Detailed Design |
+| Workflow changes | `/fluent-workflow-builder` | §4 Workflows, §5 Statuses, §6 Rulesets |
+| Settings | `/fluent-settings` | §9 Settings |
+| Module validation | `/fluent-module-validate` | §17 Deployment (step 1) |
+| Module build | `/fluent-build` | §17 Deployment (step 2) |
+| Pre-deploy check | `/fluent-pre-deploy-check` | §17 Deployment (step 3) |
+| Module deploy | `/fluent-module-deploy` | §17 Deployment (step 4) |
+| Workflow deploy | `/fluent-workflow-deploy` | §17 Deployment (steps 5-6) |
+| Data module scaffold | `/fluent-data-module-scaffold` | When the feature requires data modules (no Java) |
+| E2E verification | `/fluent-e2e-test` | §16 Test Plan |
+
+The deployment sequence in §17 defines execution order. Track tasks from §17 via TodoWrite.
+
+**Module-first deployment:** When workflows are bundled inside the module (`resources/workflows/`), `fluent module install` deploys rules, workflows, and settings together. The separate `/fluent-workflow-deploy` step (steps 5-6) is only needed for standalone workflows NOT included in the module, or when workflows were excluded during module install (`--exclude workflows`).
+
+**Critical ordering constraint:** Module deploy (registers rules) MUST complete before workflow deploy (references rules). Deploying workflows that reference unregistered custom rules causes NO_MATCH events at runtime. The §17 template enforces this: workflow deploy steps depend on module deploy.
+
+**Version bump required for any content change:** Any change to Java code, workflow JSONs, settings, or resources requires bumping the module version in BOTH `resources/module.json` AND all `pom.xml` files. See `/fluent-build` for the sync procedure.
+
+**Validation chain:** `/fluent-module-validate` -> `/fluent-build` -> `/fluent-pre-deploy-check` -> `/fluent-module-deploy`. The pre-deploy check is the final gate before deployment and produces a READY/BLOCKED verdict.
+
+## Updating a Plan Mid-Implementation
+
+Plans are living documents. Mid-implementation changes happen when discovery reveals missing artifacts, requirements change, or technical constraints emerge. This section defines the revision protocol.
+
+### When Revision is Triggered
+
+| Trigger | Example | Severity |
+|---------|---------|----------|
+| Missing artifact discovered | Rule referenced in workflow but not in plan | MEDIUM — add to plan |
+| Requirement change from user | "We also need SMS notifications" | HIGH — re-scope |
+| Technical constraint found | OOTB rule doesn't support needed parameter | MEDIUM — reclassify rule |
+| Dependency failure | Module build reveals missing import | LOW — fix in plan |
+| Test failure reveals gap | E2E test shows missing status transition | MEDIUM — add status + ruleset |
+
+### Revision Protocol
+
+1. **Increment revision** — Edit the plan file header: `Revision: N+1`, update `Updated: <today>`
+2. **Add revision log entry** — Append to the bottom of the plan:
+   ```markdown
+   ---
+   ## Revision Log
+
+   ### Revision N+1 — <date>
+   **Trigger:** <what caused the revision>
+   **Changes:**
+   - Added: <new artifacts>
+   - Modified: <changed artifacts with before → after>
+   - Removed: <artifacts no longer needed>
+   **Impact on completed work:** <what already-built artifacts are affected>
+   ```
+3. **Re-present changed sections** — Show ONLY the sections that changed, not the full plan
+4. **Require re-approval** — User must explicitly approve the revision before implementation continues
+5. **Update status.json** — Set `planRevision: N+1`, `updated: <today>`
+
+### Status Regression Rules
+
+| Current Status | Revision Type | Status After Revision |
+|---------------|--------------|----------------------|
+| `APPROVED` | Any change to plan | Stays `APPROVED` (plan revision, not status change) |
+| `IN_PROGRESS` | Additive (new rules, new rulesets, new settings) | Stays `IN_PROGRESS` |
+| `IN_PROGRESS` | Subtractive (removing rules/rulesets, changing triggers) | Regresses to `APPROVED` — re-approval of changed plan needed |
+| `IN_PROGRESS` | Structural (new workflows, changed entity types, new integrations) | Regresses to `PLANNING` — re-planning needed |
+| `VERIFIED` | Any change | Regresses to `IN_PROGRESS` — re-verification needed |
+
+> **After VERIFIED:** Features that have passed E2E verification can be archived via `/fluent-archive`, which transitions the status to `ARCHIVED`. Use `/fluent-feature-status` to inspect or update lifecycle state at any point.
+
+### Impact on Completed Work
+
+When a plan revision occurs, assess impact on already-implemented artifacts:
+
+| Already Completed | Revision Impact | Action |
+|------------------|-----------------|--------|
+| Rule scaffolded, not yet built | Plan adds new parameter to the rule | Edit the scaffolded Java class — add parameter |
+| Rule built and deployed | Plan changes rule logic | Re-scaffold is risky — edit existing source directly |
+| Workflow deployed | Plan adds new ruleset | Add ruleset via `/fluent-workflow-builder`, re-deploy |
+| Workflow deployed | Plan removes a status | **BREAKING** — check for entities at that status first |
+| Settings created | Plan changes setting value shape | Update setting value — no re-deploy needed |
+| E2E test passed | Plan adds new test case | Add test case, re-run E2E |
+
+**Critical rule:** Removing a status from a deployed workflow is a **BREAKING CHANGE** if any entities are currently at that status. Always check via GraphQL before removing:
+```
+graphql.query: { <entityType>s(status: ["<STATUS_TO_REMOVE>"], first: 1) { edges { node { ref } } } }
+```
+
+### Revision Limits
+
+- **Revision 1-3:** Normal iteration. Proceed with re-approval.
+- **Revision 4+:** Flag as "HIGH CHURN" — recommend stepping back to review the Business Spec. Frequent plan revisions often indicate incomplete requirements gathering.
+- **Scope-changing revision on VERIFIED feature:** Flag as **REGRESSION RISK** — the feature passed E2E and is now being re-opened. Require explicit justification.
+
+## Cross-References
+
+| For | Use |
+|-----|-----|
+| Plan template structure & worked examples | `PLAN_TEMPLATE.md` (in this skill directory) |
+| OOTB rule search | `plugin.list` via MCP |
+| Workflow analysis | `/fluent-workflow-analyzer` |
+| Custom code analysis | `/fluent-custom-code` |
+| Connection topology | `/fluent-connection-analysis` |
+| Requirements gathering (before planning) | `/fluent-use-case-discover` |
+| Scope decomposition (from scope docs) | `/fluent-scope-decompose` |
+| Feature reverse-engineering (existing) | `/fluent-feature-explain` |
+| Module scaffolding (if needed) | `/fluent-module-scaffold` |