---
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 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. For endpoint create or edit work, read `https://docs.flowrelay.app/setup/trigger-variants-and-event-mapping/` before choosing `triggerVariant`, `resourceIdPath`, or `relatedResourceIdPath`.
8. Check `https://docs.flowrelay.app/operate/usage-limits/` and `GET /agent/v1/plan-usage` before broad reads, polling, or repeated action previews.
9. Use `https://api.flowrelay.app` as the Agent Operations base URL.
10. Store the merchant-authorized token in an environment variable, OS keychain, secret manager, or MCP host secret configuration.
11. 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 published monthly protective limits. Authority controls what an agent may do; plan usage controls how much automated read, preview, and execution work can run in the period.

## 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. Read the trigger variants and event mapping reference before creating or editing endpoints.
4. 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.
5. Create or inspect endpoints only when capability, grant, usage, target state, safety, and product boundary all allow it.
6. Guide the merchant or separately authorized Shopify operator through Shopify Flow trigger setup.
7. Confirm first-event receipt facts without asking for private data.

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 and expansion:

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 requests for review, not product commitments.

## 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
- 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