@fluentcommerce/ai-skills 0.1.0 → 0.3.0

package/content/dev/skills/fluent-module-scaffold/SKILL.md

@@ -19,7 +19,7 @@ User asks: "I need a module for X" / "Build me a module" / "Create rules for X"
 │
 ├── 1. Discover existing modules in workspace
 │   Search: accounts/<PROFILE>/SOURCE/*/resources/module.json
-│   Also check: accounts/<PROFILE>/analysis/custom-code/source-map.json
+│   Also check: accounts/<PROFILE>/analysis/code/source-map.json
 │   List found modules with their rules and entity types
 │
 ├── 2. Check deployed modules in live environment
@@ -56,6 +56,15 @@ Before extending an existing module, verify the source is accessible:
 
 ## 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 module, OR check `accounts/<PROFILE>/tasks/` for a task plan with `Status: APPROVED`
+2. **If multi-artifact work** (module + rules + workflows + settings): STOP. Invoke `/fluent-feature-plan` first — this skill cannot be used for multi-artifact work without a feature plan
+3. **If approved plan found:** Skip to implementation, referencing the plan's §8 (Detailed Design) section
+4. **If new-module-only work with no plan:** Continue to the Planning Gate below to write a plan for this skill
+
 **After the pre-check determines a NEW module is needed, write a plan using the template from `PLAN_TEMPLATE.md` in the `fluent-feature-plan` skill.** Every table row must carry a Source column (NEW/EXISTING/MODIFIED/REUSED/OOTB).
 
 **Module-scaffold specific emphasis — ensure these are covered:**
@@ -69,10 +78,28 @@ Before extending an existing module, verify the source is accessible:
 7. **GraphQL operations (Section 4.7)** — queries and mutations the rules will execute
 8. **Detailed Design (Section 5)** — Maven directory structure, SDK version, parent POM, dependencies, package naming convention
 
-**Write the plan to:** `accounts/<PROFILE>/plans/<YYYY-MM-DD>-module-scaffold-<slug>.md`. Set `Status: PENDING`.
+**Write the plan to:** `accounts/<PROFILE>/tasks/<YYYY-MM-DD>-module-scaffold-<slug>.md`. Set `Status: PENDING`.
 
 Present the full plan content to the user and wait for approval before generating any 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).
 
+## Handoff Protocol
+
+### Signals emitted by this skill
+
+| Signal | Condition | Example |
+|--------|-----------|---------|
+| `-> READY: <path>` | Module directory scaffolded | `-> READY: accounts/HMDEV/SOURCE/fc-module-curbside/` |
+| `-> NEXT: /fluent-<skill>` | Ready for rule scaffolding | `-> NEXT: /fluent-rule-scaffold` |
+| `-> BLOCKED: <reason>` | Cannot proceed | `-> BLOCKED: PLAN_REQUIRED — Write a plan via /fluent-feature-plan` |
+| `-> SKIP: <reason>` | Existing module covers the domain | `-> SKIP: Extend existing module fc-module-hm-extensions. Use /fluent-rule-scaffold` |
+
+### Error codes
+
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| `PLAN_REQUIRED` | Scaffolding attempted without approved plan | Run `/fluent-feature-plan` first |
+| `VALIDATION_FAILED` | Module name conflicts or invalid entity types | Fix input parameters |
+
 ## When to Use
 
 - Creating a brand-new Fluent Commerce extension module from scratch
@@ -1917,6 +1944,41 @@ If `--rules` contains duplicates, deduplicate silently and warn:
 Warning: Duplicate rule name 'MyRule' removed from list.
 ```
 
+## Session Tracking
+
+When invoked, log the following to the session tracking protocol (consumed by `/fluent-session-summary` and `/fluent-session-audit-export`):
+
+**On entry:**
+```json
+{ "skill": "<this-skill-name>", "timestamp": "<ISO-8601>", "arguments": { "<key>": "<value>", "...": "..." } }
+```
+
+**On exit:**
+```json
+{ "skill": "<this-skill-name>", "outcome": "<completed|failed|skipped>", "changesProduced": ["<seq-numbers>"], "toolCallsProduced": ["<seq-numbers>"], "nextRecommended": "<from-handoff-section>" }
+```
+
+All MCP tool calls made during execution should include `"skill": "<this-skill-name>"` in their tracking record for attribution. The `arguments` object should capture the key parameters actually passed (profile, retailer, entity type, etc.) — not a fixed schema. The `nextRecommended` value comes from the Handoff section below.
+
+## Handoff
+
+| Output Artifact | Consumed By | Path |
+|----------------|-------------|------|
+| Maven project skeleton | `/fluent-rule-scaffold` (adds rules) | `accounts/<PROFILE>/SOURCE/fluentcommerce-fc-module-<name>/` |
+| Maven project skeleton | `/fluent-build` (compiles) | `accounts/<PROFILE>/SOURCE/fluentcommerce-fc-module-<name>/plugins/` |
+| module.json manifest | `/fluent-module-validate` | `accounts/<PROFILE>/SOURCE/fluentcommerce-fc-module-<name>/resources/module.json` |
+
+## Error Reporting
+
+Errors from this skill follow the standard format:
+
+| Field | Description |
+|-------|-------------|
+| `phase` | Skill phase where error occurred (e.g., `pre-check`, `validation`, `generation`, `verification`) |
+| `severity` | `CRITICAL` (blocks downstream), `HIGH` (needs fix), `MEDIUM` (advisory), `LOW` (informational) |
+| `message` | Human-readable error description |
+| `resolution` | Suggested fix or downstream skill to invoke |
+
 ## Gotchas
 
 - **OSGi symbolic name** must be unique per account. Convention: `_.<aliasNoHyphens>` (e.g., `_.hmreturns`). If two modules share the same symbolic name, deployment will fail with a cryptic OSGi error.