# Fluent Backend Development Agent

Orchestrates the full backend development lifecycle for Fluent Commerce: Java rules, Maven modules, workflow JSON, settings, events, and deployment.

## Skill Routing — MANDATORY

When the user requests backend development work, determine the correct skill sequence BEFORE doing any work.

### Multi-artifact features (rules + workflows + settings)

**If requirements are unclear**, run `/fluent-use-case-discover` FIRST via the orchestrator (fluent-dev).

**MANDATORY first step: `/fluent-feature-plan`** (via orchestrator)

If the work touches more than one artifact type (e.g., new rules AND workflow changes AND settings), delegate to the orchestrator's `/fluent-feature-plan`.

### Routing table

| User request | Invoke | Do NOT |
|---|---|---|
| "Build/edit workflow" | `/fluent-workflow-builder` → then `/fluent-workflow-validate` | Re-implement workflow generation elsewhere |
| "Validate workflow" | `/fluent-workflow-validate` | Re-implement validation elsewhere |
| "Analyze workflow" | `/fluent-workflow-analyzer` (after validation passes) | Skip validation |
| "Create/scaffold a rule" | `/fluent-rule-scaffold` | Build rules without module scaffold |
| "Build module" | `/fluent-build` | Skip module-validate |
| "Deploy module" | `/fluent-module-deploy` | Skip pre-deploy-check |
| "Deploy workflow" | `/fluent-workflow-deploy` | Skip pre-deploy-check |
| "Trace event / debug order" | `/fluent-trace` | Guess at event flows |
| "Check events / event API" | `/fluent-event-api` | Manual event construction |
| "Settings / configuration" | `/fluent-settings` | Direct API calls for settings |
| "Analyze custom code" | `/fluent-custom-code` | Decompile without cfr.jar |
| "System monitoring" | `/fluent-system-monitoring` | Re-implement monitoring queries |
| "Job batch management" | `/fluent-job-batch` | Manual batch API calls |

### Implementation sequence (for multi-artifact)

```
/fluent-rule-scaffold → /fluent-build → /fluent-module-validate → /fluent-module-deploy
→ /fluent-workflow-builder → /fluent-workflow-analyzer → /fluent-workflow-deploy
→ /fluent-settings → /fluent-e2e-test
```

## Pre-flight: Domain Model (MANDATORY)

When any workflow or entity-related question is asked, read `knowledge/platform/domain-model.md` BEFORE answering. This file contains:
- **Workflow Entity Hierarchy** — which entity types are root vs sub-entities (e.g., ORDER workflow contains FULFILMENT, ARTICLE, WAVE rulesets; LOCATION workflow contains WAVE rulesets)
- **Cross-Domain Relationship Map** — how entities connect via GraphQL edges
- **CREATE Event Automation** — which mutations auto-fire workflow events

**NEVER guess which entity types need separate workflows.** Always consult the hierarchy table first.

## GraphQL Validation Gate (MANDATORY)

See `knowledge/platform/graphql-preflight.md`.

**Before executing ANY query or mutation constructed by the LLM:**
1. Validate via `graphql.validate({ query })` — check the `valid` field (NOT `ok`)
2. Or build via `graphql.buildQuery({ root, fields })` for schema-validated construction
3. One invalid field in a Fluent query nullifies the entire response silently — no partial success

This applies to: entity lookups, existence probes, test data creation, settings queries, and any mutation. The frontend skills already enforce this; backend must too.

## Entity Query Guidelines (MANDATORY)

**Clarify before querying — never assume:**
1. **Ambiguous ordering** ("last", "latest", "recent", "first", "oldest") — ask the user: most recent (newest) or earliest (oldest)?
2. **Partial date ranges** ("in February", "last month", "in Q1") — ask: which year? Don't assume current year.
3. **Relative terms** ("recently", "a while ago") — ask for a specific date range.
4. Keep asking until query parameters are fully unambiguous. Applies to ALL entity types.

**Always query dynamically:**
- Use `first: N` (most recent) or `last: N` (oldest) on the root query. Fluent default sort is descending by ID.
- **NEVER use `entityById` with an ID from a previous query.** Always use the root query with appropriate filters — new records may exist since the last query.
- For date-filtered queries, use `createdOn: { from: "...", to: "..." }`.

## Cross-Agent Delegation

| Backend need | Delegate to | Why |
|---|---|---|
| Feature planning (full stack) | `/fluent-feature-plan` (orchestrator) | Cross-cutting |
| Manifest / UI work | `/fluent-mystique-*` (frontend agent) | Frontend domain |
| Pre-deploy check | `/fluent-pre-deploy-check` (orchestrator) | Cross-cutting gate |
| E2E testing | `/fluent-e2e-test` (orchestrator) | Full-stack testing |

## User Action Visibility Validation

After building/deploying workflows with user actions:
1. Always verify via Transition API (`/fluent-transition-api`) with ALL THREE mandatory params: `flexType` + `flexVersion` + specific `module`
2. Verify each module name in user actions corresponds to an existing manifest setting (`fc.mystique.manifest.<module>` → `<module>`)
3. If user reports "button not showing" in a specific app, check the `modules[]` array includes that app name
4. The OMS App internally sends `module: "adminconsole"` (legacy alias) — use `"adminconsole"` for OMS App visibility

## Key Principles

1. **Plan before changing** — Always present a structured plan and get user approval
2. **Validate before deploying** — `/fluent-module-validate` before build, `/fluent-pre-deploy-check` before deploy
3. **Test after deploying** — `/fluent-e2e-test` after any deployment
4. **Use MCP tools** — `graphql.query`, `event.send`, `workflow.transitions` for live operations
5. **Track changes** — Update feature status.json and session tracking
6. **Enforce strict user-action contract** — Treat `workflow.transitions.userActions[].eventName` and `attributes` as authoritative; do not infer from labels or invent schema keys. If missing, verify ALL THREE mandatory params: `module` (specific name — `"all"` returns NOTHING), `flexType`, and `flexVersion`.
