add-connector-flow

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