---
name: flowrelay-operator
description: Use when operating FlowRelay for Shopify Flow with an authorized human or agent, including setup orientation, receipt interpretation, event investigation, replay previews, diagnostics, support/expansion/feature requests, and choosing between docs, Agent Operations API, CLI, and MCP.
---

# FlowRelay Operator

FlowRelay is built from the ground up for agent operations, with receipts, scoped grants, action previews, redaction, and audit instead of raw event bodies and guesswork.

Use this skill for FlowRelay for Shopify Flow. Do not treat Wix, monday.com, Stripe, Help Scout, Sidekick, or cross-platform behavior as live.

In current usage, the expected agent surfaces are Codex, Claude Code, the FlowRelay CLI run by a coding or ops agent, direct Agent Operations API calls from customer-controlled automation, and MCP Agent Operations access where enabled. Use this skill only where the client can keep the merchant's Agent Access token private and call HTTP, CLI, or MCP tools through the same scoped FlowRelay contract.

## Start Here

1. Read `https://docs.flowrelay.app/llms.txt`.
2. Read the task-specific Markdown doc linked from that index.
3. Read `https://api.flowrelay.app/agent/v1/manifest` for edition identity, capability metadata, safety boundaries, and route names.
4. Use OpenAPI for exact contracts: `https://docs.flowrelay.app/reference/openapi/agent-operations.openapi.json`.
5. Use `https://docs.flowrelay.app/agent-access/agent-mission-playbooks/` to translate the operator's goal into context reads, safe actions, and escalation boundaries.
6. Use `https://docs.flowrelay.app/agent-access/availability-and-refusals/` before assuming a listed capability can be executed.
7. Use `https://docs.flowrelay.app/agent-access/setup-with-an-agent/` for new endpoint setup work.
8. Use `https://docs.flowrelay.app/agent-access/endpoint-swap-plan/` for existing sender, receiver, webhook, or endpoint migration work.
9. For endpoint create or edit work, read `https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/` before choosing `triggerVariant`, `resourceIdPath`, or `relatedResourceIdPath`.
10. Check `https://docs.flowrelay.app/operate/usage-limits/` and `GET /agent/v1/plan-usage` before broad reads, polling, or repeated action previews.
11. Use `https://api.flowrelay.app` as the Agent Operations base URL.
12. Store the merchant-authorized token in an environment variable, OS keychain, secret manager, or MCP host secret configuration.
13. Use authenticated Agent Operations only within the merchant-authorized grant.

## Choose The Surface

- **Docs and Markdown**: product meaning, setup guidance, safety boundaries, and recovery language.
- **Agent Operations API**: canonical machine contract for scoped reads and action previews. The formal API key remains `actionIntents`.
- **CLI**: use `npx flowrelay-agent docs`, `doctor`, safe reads, and action previews when shell access is convenient.
- **MCP Agent Operations access**: use `https://api.flowrelay.app/agent/v1/mcp` when the client supports remote MCP and the endpoint is enabled.

The CLI and MCP do not create separate authority. They wrap the same scoped Agent Operations contract.
Agent Access is included with exact meters and operational safeguards. Authority controls what an agent may do; plan usage controls how much automated read, preview, and execution work can run in the period.
If a request returns `429`, obey `Retry-After`, `retryAfterSeconds`, `resetAt`, `rateLimitClass`, `scope`, and `recommendedAction`. Narrow the target set or wait for the current window; do not retry in a tight loop. Valid signed event bursts are normally durable and buffer-first, while `429` protects loopable Agent Operations, invalid or malformed traffic, auth failures, and other operational safeguards.

## Safety Boundary

Never request, expose, copy, or store:

- endpoint secrets except one-time create or rotation responses
- authentication headers, HMAC values, signing keys, Shopify tokens, Shopify sessions, or database URLs
- raw event bodies by default
- customer data, merchant incidents, copied private logs, or store passwords

Do not silently approve billing, replay events, submit support, widen grants, create grants, revoke grants, escalate authority, edit Shopify Flow, install/uninstall the app, or claim downstream Shopify Flow branch/action completion.

`Delivered` means FlowRelay handed the trigger to Shopify Flow. It does not mean Shopify Flow branches, app calls, emails, fulfillment actions, third-party systems, or business outcomes completed.

## Operating Workflow

For setup:

1. Identify the operator mission and read the matching mission playbook.
2. Inspect manifest, grant, setup state, and plan usage before creating or changing anything.
3. Inventory the sender, platform or source type, event purpose, expected volume, criticality, auth mode, rollback owner, and intended Shopify Flow trigger before choosing fields.
4. Read the trigger variants and event mapping reference before creating or editing endpoints.
5. Choose the trigger variant from the Shopify Flow workflow need. Use `resourceIdPath` only for order, customer, or product variants; use `relatedResourceIdPath` only for inventory, fulfillment, return/refund, or company/B2B variants; use neither for generic.
6. Create or inspect one endpoint only when capability, grant, usage, target state, safety, and product boundary all allow it.
7. Guide the merchant or separately authorized Shopify operator through Shopify Flow trigger setup. Stop for operator approval before changing sender URLs, sender auth, Shopify Flow workflows, billing, grants, or secrets.
8. Confirm FlowRelay accepted and handed off one test event with synthetic data without asking for private data. State separately that downstream Shopify Flow branch/action success is outside FlowRelay's proof boundary.
9. Recommend a monitoring cadence based on traffic, criticality, recent failures, and cutover phase.
10. Produce an operator-readable summary covering inventory, endpoint choice, test result, risks, plan fit, rollback, stop conditions, and unresolved approvals.

For swapover:

1. Inventory current sender, receiver, webhook, or endpoint lanes, including platform/source type, purpose, volume, criticality, auth mode, retry behavior, and rollback path.
2. Choose one safest, least-used, rollback-friendly pilot endpoint for the first FlowRelay test.
3. Check current plan fit with `GET /agent/v1/plan-usage` before broad reads, repeated previews, or a migration plan.
4. Stop for operator approval before changing production sender URLs, sender authentication, Shopify Flow workflows, billing, grants, or secrets.
5. Prove FlowRelay accepted and handed off the pilot event. Do not claim downstream Shopify Flow workflow completion unless the operator separately verifies it in Shopify Flow.
6. Prepare the broader cutover sequence, monitoring cadence, rollback steps, stop conditions, and unresolved approvals before recommending any larger rollout.

For investigation:

1. Read event history and event detail.
2. Explain accepted, rejected, delivered, failed, duplicate, retention, and replay state from receipt facts.
3. Use support codes and docs links; state uncertainty when FlowRelay cannot prove downstream behavior.

For recovery:

1. Prefer sender resend when the sender owns the missing event or payload has expired.
2. Use FlowRelay replay only for retained events after preview, explicit confirmation, idempotency, and audit.
3. Use diagnostics shares for redacted support collaboration after preview.

For support, expansion, and feature requests:

1. Use support request preview before submit and include only redacted summaries, diagnostics IDs, event IDs, endpoint IDs, and support codes.
2. Treat expansion requests as non-binding future-edition or platform demand for review, not product commitments.
3. Treat feature requests as non-binding missing FlowRelay capability signals for review, not support tickets, expansion requests, generic wishlists, or product commitments.
4. Use `POST /agent/v1/feature-requests` only when the missing capability is inside FlowRelay's current reliability, receipts, recovery, diagnostics, Agent Operations, billing/usage, security, docs, or operator workflow surface.

## Response Style

Be concrete and bounded:

- say what FlowRelay knows from receipt facts
- say what it cannot know about downstream Shopify Flow outcomes
- name the next safe action
- include plan fit, monitoring cadence, rollback, and stop conditions when setup or swapover is involved
- cite the relevant docs URL or refusal reason
- escalate to a human when the grant, docs, manifest, or API response says the action is outside authority