rules/zuora-coding-agent.mdc

---
description: Zuora Coding Agent persistent instructions for all Zuora development work
alwaysApply: true
---

When working on Zuora-related tasks, use the zuora-mcp server for authoritative API specs, metadata, code generation, and product knowledge. All commands use the `/zuora-` prefix.

## Available commands

- `/zuora-api-design` — Propose Zuora API approach for a business requirement
- `/zuora-api-build` — Generate integration code using the selected APIs
- `/zuora-workflow-design` — Design a Zuora Workflow-based solution
- `/zuora-workflow-build` — Implement workflow assets or related code/config
- `/zuora-is-migration-design` — IS migration strategy, mappings, phases, and risks
- `/zuora-is-migration-build` — IS migration implementation artifacts
- `/zuora-order-migration-design` — Order migration design, sequencing, and edge-case analysis
- `/zuora-order-migration-build` — Order migration implementation artifacts
- `/zuora-meter-design` — Design a Zuora meter topology and operator configuration
- `/zuora-meter-build` — Compose and lint importable Zuora meter JSON
- `/zuora-dynamic-pricing-design` — Design a Commerce Catalog setup with dynamic pricing
- `/zuora-dynamic-pricing-build` — Execute the dynamic pricing setup on the tenant
- `/zuora-validate` — Validate code/payloads against Zuora patterns
- `/zuora-review` — Review work for Zuora best practices
- `/zuora-cpq-apex-design` — Design legacy CPQ Apex, Visualforce, Component Library, zQuoteUtil, controller extension, or plugin-interface customizations
- `/zuora-cpq-apex-build` — Generate CPQ Apex, Visualforce, Component Library, zQuoteUtil, controller extension, or plugin-interface artifacts into a Salesforce DX repo
- `/zuora-cpq-js-design` — Design Quote Studio or CPQ X JavaScript extensibility using supported hooks, events, quote state, and ZQFClient patterns
- `/zuora-cpq-js-build` — Generate Quote Studio or CPQ X LWC headless/sidebar components and registration notes into a Salesforce DX repo
- `/zuora-cpq-migration-design` — Map or modernize legacy CPQ customizations to Quote Studio hooks/events
- `/zuora-cpq-validate` — Validate CPQ Apex, Visualforce, LWC hooks/events, quote-state usage, ZQFClient usage, and global Apex methods
- `/zuora-cpq-review` — Review CPQ Apex, Visualforce, Quote Studio LWC, hook/event usage, registration, tests, and maintainability
- `/zuora-uat-design` — Extract TR matrix from SDDs (design/testmatrix/)
- `/zuora-uat-build` — Build test plan, API scripts, and UI docs for scoped features
- `/zuora-uat-run` — Execute API and UI tests with mark-driven verify gate

## MCP tools vs customer code

MCP tools serve three purposes:
1. **Look up specs** — use `zuora_codegen`, `ask_zuora`, `query_objects` to inform code generation.
2. **Perform operations on the tenant** — when the user asks to directly do something (e.g., "create a product," "run this workflow," "query my subscriptions"), use the appropriate MCP tool to execute it.
3. **Test/validate artifacts** — use operational tools to verify generated workflows, subscriptions, etc.

When generating code for the customer's repository, always output Zuora REST API or SDK calls — never embed MCP tool references in generated code. If the user's intent is ambiguous (do it now vs. write code for it), ask them to clarify.

## MCP tools available (via zuora-mcp)

**Metadata & guidance** (look up specs to inform code generation):
- `mcp__zuora-mcp__zuora_codegen` — API classes, endpoints, models, fields, enum values, SDK code rules. Always follow: `code_guidance` → `list_api_classes` → `get_class_apis` → `get_api_details` → `get_model_details` → `code_rules`. Never guess field names or enum values.
- `mcp__zuora-mcp__ask_zuora` — Product knowledge (Billing, Revenue, CPQ, Payments). Use only for unresolved qualitative product behavior after specialist tools are checked.
- `mcp__zuora-mcp__sdk_upgrade` — SDK version info, changelogs, upgrade guidance.

**Tenant inspection** (read live data to inform code generation):
- `mcp__zuora-mcp__query_objects` — Query 40+ Zuora object types with filtering, sorting, pagination.
- `mcp__zuora-mcp__get_account_summary` — Comprehensive account details including recent memos.

**Operational** (test/validate generated artifacts against the tenant, or other available MCP tools):
- `mcp__zuora-mcp__manage_workflows` / `mcp__zuora-mcp__manage_workflow_runs` — Discover, import/export workflows and execute, monitor, or stop workflow runs.
- `mcp__zuora-mcp__manage_mediation_meters` — Mediation meter operations: `get_meter`, `create_meter`, `validate_meter`, `list_connections`, `list_event_stores`, `list_schemas`.
- `mcp__zuora-mcp__create_subscriptions` / `manage_subscriptions` — Create or manage subscriptions for validation.
- `mcp__zuora-mcp__manage_billing_documents` — Verify billing document generation.
- Other `manage_*` tools as needed for their specific domains.

## Tool routing policy

1. Use built-in tools first for local repo facts: file reads, search, edits, tests, shell commands, and bundled reference docs.
2. Use specialist MCP tools before generic product knowledge tools: `zuora_codegen` for API specs and SDK details, `query_objects` for tenant records, `manage_workflows` / `manage_workflow_runs` for Workflow state, capabilities, and execution, `manage_mediation_meters` for meter operators and meter JSON, and managed billing/subscription tools for their specific operations.
3. Use direct HTTP first when a skill explicitly provides a credential-backed endpoint recipe and asks for raw tenant metadata; use MCP only as the documented fallback.
4. Use `mcp__zuora-mcp__ask_zuora` only when a qualitative product question remains after the sources above are checked.
5. When using `mcp__zuora-mcp__ask_zuora`, ask the exact unresolved question and mention the sources already checked. Do not call it only because a user-facing label is unfamiliar; search the bundled references and catalogs first.

## Key rules

- Never hardcode Zuora credentials — always use environment variables
- Always include `Zuora-Version` header in API calls
- Always fetch actual enum values via `get_model_details` before generating code
- Use cursor-based pagination for all list operations
- Handle `STOP_AND_CONFIRM` responses without retrying