add-connector-flow

name: add-connector-flow description: > Adds one or more payment flows (Authorize, Capture, Refund, Void, PSync, RSync, webhooks, etc.) to an existing connector in the connector-service (UCS) Rust codebase. Use when a connector already exists but is missing specific flow implementations. Handles dependency validation and sequential implementation order. license: Apache-2.0 compatibility: Requires Rust toolchain with cargo. Linux or macOS. metadata: author: parallal version: "2.0" domain: payment-connectors

Add Connector Flow

Overview

Adds specific payment flows to an existing connector.

MANDATORY SUBAGENT DELEGATION: You are the orchestrator. You MUST delegate every step to a subagent using the prompts in references/subagent-prompts.md. Do NOT implement code, run tests, or review quality yourself. Spawn subagents and coordinate their outputs.

Inputs: connector name + list of flows to add (e.g., "add Refund and RSync to AcmePay") Output: requested flows implemented, tested, and quality-reviewed

Flow Dependencies

Flows must be implemented in dependency order. A flow cannot be added unless its prerequisites already exist or are also being added in the same batch.

Full dependency graph and resolution algorithm: references/flow-dependencies.md

Critical Conventions

Include in every subagent prompt:

• Use RouterDataV2 (NEVER RouterData), ConnectorIntegrationV2 (NEVER ConnectorIntegration)
• Import from domain_types (NEVER hyperswitch_domain_models)
• NEVER hardcode status values -- always map via From/TryFrom
• Use macros for all flows. Every flow in BOTH create_all_prerequisites! and macro_connector_implementation!
• generic_type: T always present in macro_connector_implementation! for ALL flows
• Auth via req.connector_config (NOT connector_auth_type)
• No unwrap(), no None-hardcoded fields

Workflow: Orchestrator Sequence

Full subagent prompts: references/subagent-prompts.md

Step 1: State Analysis & Dependency Validation (Subagent)

Subagent prompt: references/subagent-prompts.md → Subagent 1

Inputs: connector_name, requested_flows

What it does:

1. Verifies connector exists at expected path
2. Reads connector file, lists flows already in create_all_prerequisites!
3. Reads tech spec for each requested flow's API details
4. Validates dependencies -- checks each requested flow's prerequisites exist
5. Resolves implementation order (topological sort)

Outputs: existing_flows, implementation_order, missing_prerequisites

Gates (HARD STOP — no exceptions):

• If tech spec missing → STOP IMMEDIATELY. Do NOT proceed to Step 2. Tell the user: "No tech spec found for {ConnectorName}. Please either: (1) Run the generate-tech-spec skill first, or (2) Provide the tech spec file manually at grace/rulesbook/codegen/references/{connector_name}/technical_specification.md." Do NOT attempt to infer API details from existing connector code or any other source. A tech spec is mandatory — never skip this requirement.
• If prerequisites missing → STOP, inform user what to add first.

Step 2: Flow Implementation (MANDATORY subagent per flow, sequential)

CRITICAL: You MUST delegate each flow to a subagent. Do NOT implement code yourself. Read the subagent prompt from references/subagent-prompts.md → Subagent 2, fill in the variables ({ConnectorName}, {FlowName}, tech spec path), and spawn a subagent for EACH flow. Wait for each subagent to complete before spawning the next.

Detailed procedure: references/flow-implementation-guide.md Per-flow patterns: references/flow-patterns/{flow}.md

Implement each flow in the resolved order from Step 1. Spawn one subagent per flow.

Each flow subagent does:

1. Reads tech spec for this flow's endpoint
2. Reads references/flow-patterns/{flow}.md
3. Adds flow to create_all_prerequisites!
4. Adds macro_connector_implementation! block
5. Creates transformer types + TryFrom impls
6. Adds trait marker implementation
7. Runs cargo build --package connector-integration

Flow type quick reference (full table in references/flow-implementation-guide.md):

Trait marker names (not uniform -- use exact names):

Step 3: gRPC Testing (MANDATORY subagent)

CRITICAL: You MUST delegate testing to a subagent. Do NOT run grpcurl yourself. Subagent prompt: references/subagent-prompts.md → Subagent 3 Testing guide: references/grpc-testing-guide.md

Inputs: connector_name, list of newly added flows

What it does:

1. Starts gRPC server
2. Loads credentials from creds.json
3. Tests each new flow via grpcurl
4. Validates responses (PASS/FAIL criteria in testing guide)
5. If failed: reads server logs, fixes code, rebuilds, retests (max 7 iterations)

gRPC service mapping (full table in testing guide):

Gate: All new flows must pass before proceeding.

Step 4: Quality Review (MANDATORY subagent)

CRITICAL: You MUST delegate quality review to a subagent. Do NOT review yourself. Subagent prompt: references/subagent-prompts.md → Subagent 4 Checklist: references/quality-checklist.md

What it does:

1. Architecture compliance (no legacy types)
2. Status mapping (no hardcoded statuses)
3. Code quality (no unwrap, descriptive errors)
4. Consistency with existing flows in this connector
5. Final cargo build

Supported Flows Catalog

Reference Index