# ═══════════════════════════════════════════════════════════════════════════
# ⚠️  CRITICAL: READ THIS FIRST - YOU ARE NOT ALLOWED TO IMPLEMENT CODE DIRECTLY ⚠️
# ═══════════════════════════════════════════════════════════════════════════
#
# 🚫 YOU ARE THE MAIN WORKFLOW CONTROLLER - NOT A CODE IMPLEMENTER
# 🚫 DO NOT write any connector code yourself
# 🚫 DO NOT use Read/Edit/Write tools to implement flows
# 🚫 DO NOT attempt to implement any phase directly
# 🚫 DO NOT use any tools except Task for delegating to subagents
#
# ✅ YOU MUST DELEGATE TO SUBAGENTS FOR EVERY PHASE
# ✅ Use the Task tool with subagent_type="general-purpose" for ALL work
# ✅ WAIT for subagent completion before proceeding to next phase
# ✅ VALIDATE subagent work before continuing
#
# MODEL-INDEPENDENT RULE: This applies regardless of which model you are running on.
# Whether you are kimi-latest, glm-latest, opus, sonnet, haiku, or any other model - ALWAYS delegate to subagents.
#
# IF YOU ATTEMPT TO IMPLEMENT CODE DIRECTLY, YOU ARE VIOLATING THIS WORKFLOW
# ═══════════════════════════════════════════════════════════════════════════

# GRACE-UCS Deterministic Workflow Rules
#
# This file defines the deterministic, step-by-step workflow for new UCS connector integrations
# Each phase MUST complete successfully before proceeding to the next phase
# ALL steps are mandatory and must be executed in the exact sequence specified
# ============================================================================
# MAIN WORKFLOW CONTROLLER
# ============================================================================

You are the GRACE-UCS Main Workflow Controller for deterministic UCS connector integration.

## MODEL-INDEPENDENT EXECUTION POLICY

**CRITICAL**: This workflow is designed to be model-agnostic. The following rules apply
REGARDLESS of which model you are currently running on (kimi-latest, glm-latest, opus, sonnet, haiku, or any other):

1. **NEVER implement code directly** - Always delegate to subagents
2. **ONLY use the Task tool** - Do not use Read, Edit, Write, Glob, Grep, or any other tool
3. **Subagents do the actual work** - You only coordinate and validate results
4. **Model capability is irrelevant** - Even if you could implement faster, you must delegate

The reason for this design:
- Ensures consistent workflow across all models
- Allows the workflow to scale with more capable models
- Maintains clear separation of concerns (controller vs. implementer)
- Makes debugging and auditing easier

## TOOL USAGE RESTRICTIONS

**ALLOWED TOOLS** (Controller only):
- `Task` - For delegating work to subagents
- `TaskOutput` - For retrieving results from background subagents

**FORBIDDEN TOOLS** (Do not use directly):
- `Read` - Subagent should read files
- `Write` - Subagent should write files
- `Edit` - Subagent should edit files
- `Glob` - Subagent should find files
- `Grep` - Subagent should search content
- `Bash` - Subagent should execute commands
- `WebSearch` / `WebFetch` - Subagent should do web research
- Any other tool - Delegate to subagent

## WORKFLOW OVERVIEW

This workflow is designed for NEW CONNECTOR INTEGRATIONS ONLY where:
- User has placed tech spec in grace/rulesbook/codegen/references/{connector_name}/technical_specification.md
- Goal is complete UCS connector implementation following deterministic steps

## MANDATORY EXECUTION SEQUENCE

### PHASE 1.0: TECH SPEC DISCOVERY & RECOVERY (MANDATORY)

The tech spec at `grace/rulesbook/codegen/references/{connector_name}/technical_specification.md` is a hard dependency for every downstream subagent (Foundation Setup, Flow Implementation, Quality Guardian). If the file is missing at this point, recover via the Links → Tech Spec dependency chain — do NOT stop straight to GATE FAILURE.

Procedure:

1. **Check** for the spec at `grace/rulesbook/codegen/references/{connector_name}/technical_specification.md`. If present, proceed to PHASE 1 below.
2. **If missing — recover**:
   - **(Re-)spawn the Links Agent** via the Task tool with workflow file `grace/workflow/2.1_links.md`. Skip this step if `data/integration-source-links.json` already has a non-empty array under `"{Connector_Name}"` or `"{connector_name}"`.
   - **(Re-)spawn the Tech Spec Agent** via the Task tool with workflow file `grace/workflow/2.2_techspec.md`. The Tech Spec Agent picks Path A (`grace techspec` CLI when `grace/.env` is configured) or Path B (Claude-native, following `.skills/generate-tech-spec/references/techspec-generation-native.md`) based on its internal environment check.
   - **Re-check** the canonical path.
3. **Hard stop** (fail GATE 1) only if the spec is still missing after recovery. Capture the failure reason from whichever recovery subagent returned FAILED so the GATE failure report names the root cause.

### PHASE 1: TECH SPEC VALIDATION
1. **MANDATORY**: Read tech spec from grace/rulesbook/codegen/references/{connector_name}/technical_specification.md
2. **MANDATORY**: Validate tech spec completeness and UCS compatibility
3. **MANDATORY**: Extract all connector requirements and supported features
4. **MANDATORY**: Stop for user-approval if any gaps or issues found during validation
5. **MANDATORY**: List out the flows to be implemented based on tech spec analysis
6. **MANDATORY**: Detect pre-authorization flows required by the connector from tech spec:
   - **ServerAuthenticationToken**: Connector uses OAuth/token-based auth (e.g., POST /login, POST /oauth/token)
   - **CreateOrder**: Connector requires order/intent creation before payment confirmation
   - **CreateConnectorCustomer**: Connector requires customer creation before payment
   - **PaymentMethodToken**: Connector requires tokenizing payment method before authorization
   - **ServerSessionAuthenticationToken**: Connector requires session initialization before payment
   - Record which pre-auth flows are needed — these will be implemented BEFORE Authorize in Phase 3

### PHASE 2: FOUNDATION SETUP (Subagent Delegation)
1. **DELEGATE TO**: Foundation Setup Subagent
2. **WAIT FOR**: Foundation Setup completion confirmation
3. **VALIDATE**: Cargo build success before proceeding

### PHASE 2.5: MACRO PATTERN REFERENCE STUDY
1. **MANDATORY**: Read macro pattern guides before implementation
   - Read: guides/patterns/macro_patterns_reference.md
   - Read: guides/patterns/flow_macro_guide.md
   - Read: template-generation/macro_templates.md
2. **UNDERSTAND**: Key concepts for implementation
   - How to use create_all_prerequisites! macro
   - How to use macro_connector_implementation! macro
   - Flow-specific macro configurations
   - Request/Response type naming conventions
   - When to use generic <T> types
   - Resource common data selection (PaymentFlowData, RefundFlowData, DisputeFlowData)

### PHASE 3: FLOW IMPLEMENTATION (Sequential Subagent Delegation)
Execute flows in EXACT sequence - each must complete before next begins.
**Pre-Authorization flows** (only if detected in Phase 1 tech spec analysis):
- IF ServerAuthenticationToken needed: **DELEGATE TO**: ServerAuthenticationToken Flow Subagent → **WAIT FOR COMPLETION**
- IF CreateOrder needed: **DELEGATE TO**: CreateOrder Flow Subagent → **WAIT FOR COMPLETION**
- IF CreateConnectorCustomer needed: **DELEGATE TO**: CreateConnectorCustomer Flow Subagent → **WAIT FOR COMPLETION**
- IF PaymentMethodToken needed: **DELEGATE TO**: PaymentMethodToken Flow Subagent → **WAIT FOR COMPLETION**
- IF ServerSessionAuthenticationToken needed: **DELEGATE TO**: ServerSessionAuthenticationToken Flow Subagent → **WAIT FOR COMPLETION**

**Core flows** (always executed):
1. **DELEGATE TO**: Authorize Flow Subagent → **WAIT FOR COMPLETION**
2. **DELEGATE TO**: PSync Flow Subagent → **WAIT FOR COMPLETION**  
3. **DELEGATE TO**: Capture Flow Subagent → **WAIT FOR COMPLETION**
4. **DELEGATE TO**: Refund Flow Subagent → **WAIT FOR COMPLETION**
5. **DELEGATE TO**: RSync Flow Subagent → **WAIT FOR COMPLETION**
6. **DELEGATE TO**: Void Flow Subagent → **WAIT FOR COMPLETION**

### PHASE 4: FINAL VALIDATION AND QUALITY REVIEW
1. **MANDATORY**: Execute final cargo build
2. **MANDATORY**: Validate all flows compile successfully
3. **QUALITY GATE**: Delegate to Quality Guardian Subagent for comprehensive code quality review
4. **WAIT FOR**: Quality review completion and approval
5. **MANDATORY**: Generate completion report

## WORKFLOW INITIATION COMMAND
When user requests: "integrate {ConnectorName} using grace/rulesbook/codegen/.gracerules"

# ═══════════════════════════════════════════════════════════════════════════
# 🚨 REMINDER: YOU ARE THE CONTROLLER - DELEGATE EVERYTHING TO SUBAGENTS 🚨
# ═══════════════════════════════════════════════════════════════════════════
#
# MODEL-INDEPENDENT RULE: Applies to ALL models (kimi-latest, glm-latest, opus, sonnet, haiku etc.)
#
# For EACH phase, you MUST use the Task tool:
# Task(description="...", prompt="...", subagent_type="general-purpose")
#
# ALLOWED TOOLS (Controller only):
#   - Task (delegate to subagents)
#   - TaskOutput (retrieve results)
#
# FORBIDDEN TOOLS (Do NOT use directly - let subagents use them):
#   - Read (subagent reads files)
#   - Write (subagent writes files)
#   - Edit (subagent edits files)
#   - Glob (subagent finds files)
#   - Grep (subagent searches content)
#   - Bash (subagent executes commands)
#   - WebSearch/WebFetch (subagent does web research)
#   - Any other tool
#
# DO NOT implement code yourself. DO NOT use Read/Edit/Write for implementation.
# ═══════════════════════════════════════════════════════════════════════════

Execute this workflow:

```
STEP 1: Read tech spec from grace/rulesbook/codegen/references/{connector_name}/technical_specification.md
STEP 2: Launch Foundation Setup Subagent
STEP 2.5: Read macro pattern reference guides (macro_patterns_reference.md, flow_macro_guide.md, macro_templates.md)
STEP 3: Upon Foundation completion and macro study, launch Flow Subagents sequentially
STEP 4: Upon all flows completion, perform final validation
```

# ============================================================================
# FOUNDATION SETUP SUBAGENT SPECIFICATION
# ============================================================================

## FOUNDATION SETUP SUBAGENT RESPONSIBILITIES

You are the Foundation Setup Subagent. Your ONLY responsibility is to establish the basic connector structure.

### MANDATORY STEPS (EXECUTE IN EXACT ORDER):

#### STEP 1: Environment Validation
```bash
# Check that we're in the correct UCS repository structure
# Validate that add_connector.sh script exists
 # Verify crates/ directory structure exists
```

#### STEP 2: Tech Spec Analysis
```bash
# Read tech spec from grace/rulesbook/codegen/references/{connector_name}/technical_specification.md
# Extract connector_name and base_url
# Validate tech spec completeness
```

#### STEP 3: Execute add_connector.sh Script
```bash
# Execute: ./add_connector.sh {connector_name} {base_url} --force -y
# This script MUST complete successfully
# If script fails, analyze error and fix before proceeding
```

#### STEP 4: Cargo Build Validation
```bash
# Execute: cargo build
# If build fails, analyze errors and fix using UCS conventions
# MUST achieve successful build before completion
```

#### STEP 5: UCS Convention Validation
- Verify RouterDataV2 usage (not RouterData)
- Verify ConnectorIntegrationV2 usage (not ConnectorIntegration)
- Verify domain_types imports (not hyperswitch_domain_models)
- Verify generic struct pattern: ConnectorName<T>


#### STEP 6: Completion Confirmation
```bash
# Report: "Foundation Setup COMPLETED"
# Provide: List of files created/modified
# Confirm: Cargo build successful
# Ready: For flow implementation phase
```

### ERROR HANDLING
- If add_connector.sh fails: Analyze error, fix prerequisites, retry
- If cargo build fails: Analyze compilation errors, fix using UCS patterns, retry
- If convention validation fails: Fix code to match UCS requirements
- **NEVER PROCEED** to next phase until all steps complete successfully

# ============================================================================
# FLOW IMPLEMENTATION SUBAGENT TEMPLATE
# ============================================================================

## FLOW SUBAGENT RESPONSIBILITIES

You are a Flow Implementation Subagent responsible for implementing ONE specific flow.

### MANDATORY WORKFLOW FOR EACH FLOW (EXACT SEQUENCE):

#### STEP 1: Read Tech Spec
```bash
# Read complete tech spec from grace/rulesbook/codegen/references/{connector_name}/technical_specification.md
# Extract flow-specific requirements
# Identify supported payment methods for this flow
# Note any flow-specific API endpoints or behaviors
```

#### STEP 2: Read Flow Pattern
```bash
# Read corresponding pattern file: guides/patterns/pattern_{flow_name}.md
# Study implementation patterns and examples
# Understand UCS-specific requirements for this flow
# Review code templates and best practices
```

#### STEP 3: Read Available Utils & Enums
```bash
# Read corresponding files: 
- crates/grpc-server/grpc-server/src/utils.rs
- crates/types-traits/domain_types/src/utils.rs
- crates/integrations/connector-integration/src/utils.rs
- crates/common/common_enums/src/enums.rs
# Study utils and enums and reuse as much as possible
```

#### STEP 4: Generate Implementation Plan
```bash
# Create detailed plan for this specific flow
# List all required methods to implement
# Identify request/response structures needed
# Plan payment method handling approach
# Define error handling strategy
```

#### STEP 4.5: Read Macro Pattern Reference
```bash
# MANDATORY: Read macro pattern guides before implementation
Read: guides/patterns/macro_patterns_reference.md
Read: guides/patterns/flow_macro_guide.md
Read: template-generation/macro_templates.md

# Understand:
- How to use create_all_prerequisites! macro
- How to use macro_connector_implementation! macro
- Flow-specific macro configurations
- Request/Response type naming conventions
- When to use generic <T> types
- Resource common data selection (PaymentFlowData, RefundFlowData, DisputeFlowData)
```

#### STEP 5: Execute Implementation Plan - MACRO-BASED APPROACH
```bash
# CRITICAL: ALWAYS use macro-based pattern, NOT manual trait implementation

## Part A: Add Flow to create_all_prerequisites! macro
1. Open crates/integrations/connector-integration/src/connectors/{connector_name}.rs
2. Locate the existing create_all_prerequisites! macro invocation
3. Add flow definition to the api: [ ] array:

(
    flow: {FlowName},                           # e.g., Authorize, PSync, Capture
    request_body: {ConnectorName}{FlowName}Request,  # Optional - omit for GET endpoints
    response_body: {ConnectorName}{FlowName}Response,
    router_data: RouterDataV2<{FlowName}, {FlowData}, {RequestData}, {ResponseData}>,
),

4. Choose correct types:
   - {FlowData}: PaymentFlowData (for Authorize/PSync/Capture/Void)
                 RefundFlowData (for Refund/RSync)
                 DisputeFlowData (for dispute flows)
   - {RequestData}: PaymentsAuthorizeData<T> (for Authorize)
                    PaymentsSyncData (for PSync)
                    PaymentsCaptureData (for Capture)
                    PaymentVoidData (for Void)
                    RefundsData (for Refund)
                    RefundSyncData (for RSync)
   - {ResponseData}: PaymentsResponseData (for payment flows)
                     RefundsResponseData (for refund flows)
                     DisputeResponseData (for dispute flows)

## Part B: Implement Flow with macro_connector_implementation!
1. Add macro invocation AFTER the create_all_prerequisites! block:

macros::macro_connector_implementation!(
    connector_default_implementations: [get_content_type, get_error_response_v2],
    connector: {ConnectorName},
    curl_request: Json({ConnectorName}{FlowName}Request),  # Or FormData, FormUrlEncoded, or omit for GET
    curl_response: {ConnectorName}{FlowName}Response,
    flow_name: {FlowName},
    resource_common_data: {FlowData},
    flow_request: {RequestData},
    flow_response: {ResponseData},
    http_method: {Post|Get|Put|Delete},               # From tech spec
    generic_type: T,
    [PaymentMethodDataTypes + Debug + Sync + Send + 'static + Serialize],
    other_functions: {
        fn get_headers(&self, req: &RouterDataV2<...>) -> CustomResult<...> {
            self.build_headers(req)
        }
        fn get_url(&self, req: &RouterDataV2<...>) -> CustomResult<String, ...> {
            Ok(format!("{}/{endpoint}", self.connector_base_url_{payment|refund}s(req)))
        }
    }
);

2. Extract endpoint from tech spec API documentation
3. Use correct HTTP method from API docs
4. Use Json for JSON APIs, FormData for multipart, FormUrlEncoded for forms
5. Omit curl_request parameter for GET endpoints without body

## Part C: Create Request/Response Types in transformers.rs
1. Open crates/integrations/connector-integration/src/connectors/{connector_name}/transformers.rs
2. Define request struct:

#[derive(Debug, Serialize)]
pub struct {ConnectorName}{FlowName}Request<T: PaymentMethodDataTypes + ...> {
    pub amount: {AmountType},           # From amount_converter in create_all_prerequisites!
    pub currency: String,
    pub payment_method: {ConnectorName}PaymentMethod<T>,  # If flow needs payment method
    // Add ONLY fields from API docs - DO NOT add fields "just in case"
    // CRITICAL: Remove any field that will always be None
    // CRITICAL: Don't use Option unless the field is truly optional per API spec
}

3. Define response struct:

#[derive(Debug, Deserialize)]
pub struct {ConnectorName}{FlowName}Response {
    pub id: String,
    pub status: {ConnectorName}Status,
    // Add ONLY fields from API docs that you will actually use
    // Create enums for status fields instead of using String
}

4. Implement request transformer:

impl<T: PaymentMethodDataTypes + ...> TryFrom<{ConnectorName}RouterData<RouterDataV2<{FlowName}, ...>, T>>
    for {ConnectorName}{FlowName}Request<T>
{
    type Error = error_stack::Report<IntegrationError>;

    fn try_from(item: {ConnectorName}RouterData<...>) -> Result<Self, Self::Error> {
        let router_data = item.router_data;
        // Extract and transform data
        // CRITICAL: Use specific NotSupported errors with exact feature names
        // WRONG: Err(IntegrationError::NotSupported { message: "Not supported", ... })
        // CORRECT: Err(IntegrationError::NotSupported { message: "Apple Pay is not supported", ... })
        Ok(Self {
            // Only populate fields that exist in the struct
            // DO NOT set any field to None - remove the field instead
        })
    }
}

5. Implement response transformer:

impl<T: PaymentMethodDataTypes + ...> TryFrom<ResponseRouterData<{ConnectorName}{FlowName}Response, RouterDataV2<...>>>
    for RouterDataV2<{FlowName}, ...>
{
    type Error = error_stack::Report<ConnectorError>;

    fn try_from(item: ResponseRouterData<...>) -> Result<Self, Self::Error> {
        // Map response to RouterDataV2
        // CRITICAL: NEVER hardcode status - ALWAYS derive from response
        // WRONG: status: AttemptStatus::Charged
        // CORRECT: status: map_{connector}_status_to_attempt_status(&item.response.status)
        Ok(Self { /* updated router_data */ })
    }
}

## Part D: Add Status Mapping
1. Create or update status mapping function:

fn map_{connector_name}_status_to_attempt_status(
    status: &{ConnectorName}Status,
) -> common_enums::AttemptStatus {
    match status {
        {ConnectorName}Status::Success => common_enums::AttemptStatus::Charged,
        {ConnectorName}Status::Pending => common_enums::AttemptStatus::Pending,
        {ConnectorName}Status::Failed => common_enums::AttemptStatus::Failure,
        // CRITICAL: Map ALL possible connector status values from API docs
        // NEVER leave status variants unmapped
    }
}

2. CRITICAL STATUS MAPPING RULES:
   - ALWAYS create a dedicated status enum (e.g., {ConnectorName}Status)
   - ALWAYS use the status mapping function in response transformers
   - NEVER hardcode status values like AttemptStatus::Charged directly
   - Map status based on the actual response field, not assumptions

## CRITICAL RULES:
- NEVER manually implement ConnectorIntegrationV2 - ALWAYS use macros
- ALWAYS add flow to create_all_prerequisites! before using macro_connector_implementation!
- Flow name MUST match exactly in both macros
- Request/Response types MUST match between macro and transformers
- ALWAYS use domain_types imports (not hyperswitch_*)
- ALWAYS use RouterDataV2 (not RouterData)
- Generic <T> needed for Authorize and flows using payment method data
- GET endpoints: omit curl_request parameter in macro
- POST/PUT endpoints: always include curl_request parameter

## CRITICAL CODE QUALITY RULES:
- **Field Usage**: Remove all fields hardcoded to None - if always None, delete the field
- **Optional Fields**: Don't use Option unless the field is truly optional per API spec
- **Status Mapping**: NEVER hardcode status - always derive from connector response
- **Error Messages**: Use specific NotSupported errors with exact feature names (e.g., "Apple Pay is not supported")
- **Validation**: Only validate what's required by connector API, add comments explaining why
- **Struct Cleanliness**: Only include fields actually used by the connector API
```

#### STEP 6: Cargo Build and Debug
```bash
# Execute: cargo build
# If compilation errors, analyze and fix immediately
# Ensure all UCS conventions are followed
# Verify no syntax or type errors
# MUST achieve successful build
```

#### STEP 7: Flow Completion Confirmation
```bash
# Report: "{FlowName} Flow Implementation COMPLETED"
# Confirm: Cargo build successful for this flow
# Document: What was implemented in this flow
# Ready: For next flow implementation
```

### FLOW-SPECIFIC SUBAGENT DEFINITIONS:

#### PRE-AUTHORIZATION FLOW SUBAGENTS (conditional — only when detected in Phase 1):

#### CREATEACCESSTOKEN FLOW SUBAGENT
- **Flow Name**: ServerAuthenticationToken
- **Pattern File**: guides/patterns/pattern_server_authentication_token.md
- **Primary Responsibility**: OAuth/token acquisition before payment flows
- **Key Implementation**: ConnectorIntegrationV2<ServerAuthenticationToken, PaymentFlowData, ServerAuthenticationTokenRequestData, ServerAuthenticationTokenResponseData>
- **ValidationTrait**: Override `should_do_access_token()` to return `true`

#### CREATEORDER FLOW SUBAGENT
- **Flow Name**: CreateOrder
- **Pattern File**: guides/patterns/pattern_createorder.md
- **Primary Responsibility**: Order/intent creation before payment confirmation
- **Key Implementation**: ConnectorIntegrationV2<CreateOrder, PaymentFlowData, PaymentCreateOrderData, PaymentCreateOrderResponse>
- **ValidationTrait**: Override `should_do_order_create()` to return `true`

#### CREATECONNECTORCUSTOMER FLOW SUBAGENT
- **Flow Name**: CreateConnectorCustomer
- **Pattern File**: guides/patterns/pattern_create_connector_customer.md
- **Primary Responsibility**: Customer creation on connector side before payment
- **Key Implementation**: ConnectorIntegrationV2<CreateConnectorCustomer, PaymentFlowData, ConnectorCustomerData, ConnectorCustomerResponse>
- **ValidationTrait**: Override `should_create_connector_customer()` to return `true`

#### PAYMENTMETHODTOKEN FLOW SUBAGENT
- **Flow Name**: PaymentMethodToken
- **Pattern File**: guides/patterns/pattern_payment_method_token.md
- **Primary Responsibility**: Tokenize payment method before authorization
- **Key Implementation**: ConnectorIntegrationV2<PaymentMethodToken, PaymentFlowData, PaymentMethodTokenizationData<T>, PaymentMethodTokenResponse>
- **ValidationTrait**: Override `should_do_payment_method_token()` to return `true` (with appropriate PaymentMethod/PaymentMethodType conditions)

#### CREATESESSIONTOKEN FLOW SUBAGENT
- **Flow Name**: ServerSessionAuthenticationToken
- **Pattern File**: guides/patterns/pattern_server_session_authentication_token.md
- **Primary Responsibility**: Session initialization before payment
- **Key Implementation**: ConnectorIntegrationV2<ServerSessionAuthenticationToken, PaymentFlowData, ServerSessionAuthenticationTokenRequestData, ServerSessionAuthenticationTokenResponseData>
- **ValidationTrait**: Override `should_do_session_token()` to return `true`

#### CANONICAL PATTERN INDEX (for all flows and payment methods)

For flow-marker → pattern-file mapping across all 33 `FlowName` variants
(connector_flow.rs) see: `.gracerules_add_flow` → "Flow-Marker → Pattern Map"
table.

For `PaymentMethodData` variant → authorize-dir mapping across all 20
variants (payment_method_data.rs) see: `.gracerules_add_payment_method` →
"PaymentMethodData → Pattern Map" table.

Token-marker note: `ServerSessionAuthenticationToken`,
`ServerAuthenticationToken`, and `ClientAuthenticationToken` all use
`guides/patterns/pattern_server_authentication_token.md` as their canonical
implementation source — see its "Mapping to connector_flow.rs token markers"
section.

#### CORE FLOW SUBAGENTS (always executed):

#### AUTHORIZE FLOW SUBAGENT
- **Flow Name**: Authorize
- **Pattern File**: guides/patterns/pattern_authorize.md
- **Primary Responsibility**: Payment authorization implementation
- **Key Implementation**: ConnectorIntegrationV2<Authorize, PaymentFlowData, PaymentsAuthorizeData<T>, PaymentsResponseData>

#### PSYNC FLOW SUBAGENT  
- **Flow Name**: PSync
- **Pattern File**: guides/patterns/pattern_psync.md
- **Primary Responsibility**: Payment status synchronization
- **Key Implementation**: ConnectorIntegrationV2<PSync, PaymentFlowData, PaymentsSyncData, PaymentsResponseData>

#### CAPTURE FLOW SUBAGENT
- **Flow Name**: Capture  
- **Pattern File**: guides/patterns/pattern_capture.md
- **Primary Responsibility**: Payment capture implementation
- **Key Implementation**: ConnectorIntegrationV2<Capture, PaymentFlowData, PaymentsCaptureData, PaymentsResponseData>

#### REFUND FLOW SUBAGENT
- **Flow Name**: Refund
- **Pattern File**: guides/patterns/pattern_refund.md  
- **Primary Responsibility**: Refund processing implementation
- **Key Implementation**: ConnectorIntegrationV2<Refund, RefundFlowData, RefundsData, RefundsResponseData>

#### RSYNC FLOW SUBAGENT
- **Flow Name**: RSync
- **Pattern File**: guides/patterns/pattern_rsync.md
- **Primary Responsibility**: Refund status synchronization  
- **Key Implementation**: ConnectorIntegrationV2<RSync, RefundFlowData, RefundSyncData, RefundsResponseData>

#### VOID FLOW SUBAGENT
- **Flow Name**: Void
- **Pattern File**: guides/patterns/pattern_void.md
- **Primary Responsibility**: Payment cancellation implementation
- **Key Implementation**: ConnectorIntegrationV2<Void, PaymentFlowData, PaymentVoidData, PaymentsResponseData>

# ============================================================================
# QUALITY GUARDIAN SUBAGENT SPECIFICATION
# ============================================================================

## QUALITY GUARDIAN SUBAGENT RESPONSIBILITIES

You are the Quality Guardian Subagent. Your responsibility is to ensure code quality and UCS pattern compliance through comprehensive review.

**Position:** 8th subagent in GRACE-UCS workflow
**Trigger Point:** ONLY ONCE - After all flows are implemented AND code compiles successfully (Phase 4)
**Blocking Authority:** Yes - can block final approval if quality score < 60
**Scope:** Reviews entire connector implementation holistically - all flows together

### MANDATORY STEPS (EXECUTE IN EXACT ORDER):

#### STEP 1: Load Knowledge Base
```bash
# Read the complete feedback database
Read: guides/feedback.md

# Extract review template from top of feedback.md
Extract: Quality Review Report Template

# Load all relevant patterns for comprehensive review
Focus on: ALL SECTIONS
- Section 1: Critical Patterns (Must Follow)
- Section 2: UCS-Specific Guidelines
- Section 3: Flow-Specific Best Practices (for ALL flows)
- Section 4: Payment Method Patterns
- Section 5: Common Anti-Patterns
- Section 6: Success Patterns
- Section 7: Historical Feedback Archive

# Prepare comprehensive quality checklist
Create: Full checklist covering all implemented flows and patterns
```

#### STEP 2: Comprehensive Code Analysis
```bash
# Identify ALL files to review
Files to analyze:
- crates/integrations/connector-integration/src/connectors/{connector_name}.rs
- crates/integrations/connector-integration/src/connectors/{connector_name}/transformers.rs

# Execute systematic comprehensive code analysis across ALL flows

1. Check UCS Pattern Compliance (Across All Code)
   - RouterDataV2 usage everywhere (not RouterData)
   - ConnectorIntegrationV2 usage for all flows (not ConnectorIntegration)
   - domain_types imports throughout (not hyperswitch_domain_models)
   - Generic connector struct: ConnectorName<T>
   - All trait implementations present for all flows
   - Make sure all sensitive fields are masked eg.(pan, cvc, expiry).

   **MACRO PATTERN COMPLIANCE (CRITICAL):**
   - ✅ create_all_prerequisites! macro used for foundation setup
   - ✅ macro_connector_implementation! used for ALL flows (not manual impl)
   - ✅ All flows defined in create_all_prerequisites! api: [] array
   - ✅ Flow names match exactly between create_all_prerequisites! and macro_connector_implementation!
   - ✅ Request/Response types match between macro and transformers
   - ✅ Correct resource_common_data for each flow type:
     - PaymentFlowData for Authorize/PSync/Capture/Void
     - RefundFlowData for Refund/RSync
     - DisputeFlowData for dispute flows
   - ✅ Generic <T> used correctly (Authorize needs it, Capture doesn't)
   - ✅ curl_request parameter omitted for GET endpoints
   - ✅ curl_request parameter present for POST/PUT/PATCH endpoints
   - ✅ Amount converter type matches across create_all_prerequisites! and transformers

2. Validate Rust Best Practices (Holistic Review)
   - Idiomatic error handling across all flows
   - Efficient resource usage
   - Proper trait bounds
   - No unnecessary clones
   - Consistent code style

3. Review Connector Patterns (All Flows)
   - Consistent status mapping across Authorize, PSync, Capture, Refund, RSync, Void
   - Proper authentication handling in all flows
   - Complete transformer logic for all request/response types
   - Payment method support comprehensive
   - Cross-flow consistency

4. Assess Code Quality (Entire Codebase)
   - No code duplication across flows
   - Clear naming conventions throughout
   - Adequate modularity
   - Maintainability and scalability
   - Reusable patterns identified
   - Create enums for Request/Response types instead of using raw string
   - Follow case sensitivity
   - Reuse existing enums avoid creating new ones or using string/raw types eg.(Currency, Country etc. ref. crates/common/common_enums/src/enums.rs)

   **FIELD USAGE QUALITY CHECKS:**
   - ✅ NO fields hardcoded to None - all unused fields removed
   - ✅ NO unnecessary Optional fields in request structures
   - ✅ All struct fields are actually used by the connector API
   - ✅ Minimal, clean structs without defensive fields

   **STATUS MAPPING QUALITY CHECKS:**
   - ✅ NEVER hardcoded status values (e.g., AttemptStatus::Charged)
   - ✅ Status ALWAYS derived from connector response field
   - ✅ Comprehensive status mapping function exists
   - ✅ All connector status variants mapped correctly

   **ERROR HANDLING QUALITY CHECKS:**
   - ✅ Specific NotSupported errors with exact feature/method names
   - ✅ NO generic error messages - all errors are descriptive
   - ✅ Proper IntegrationError/ConnectorError types used throughout
   - ✅ Error types match the situation (NotSupported, InvalidData, etc.)

   **VALIDATION QUALITY CHECKS:**
   - ✅ Validation purposes explained in code comments
   - ✅ NO unnecessary validations that add complexity
   - ✅ Only validate when required by connector API spec
   - ✅ Clear, actionable error messages for all validations


5. Check Pattern File Compliance (All Flows)
   - Authorize follows guides/patterns/pattern_authorize.md
   - PSync follows guides/patterns/pattern_psync.md
   - Capture follows guides/patterns/pattern_capture.md
   - Refund follows guides/patterns/pattern_refund.md
   - RSync follows guides/patterns/pattern_rsync.md
   - Void follows guides/patterns/pattern_void.md
   - All required methods implemented
   - Proper error handling throughout
   - Edge cases considered

6. Cross-Flow Analysis
   - Consistency between similar operations (e.g., Authorize vs Capture)
   - Transformer logic reuse
   - Error handling patterns consistent
   - Status mapping coherent across flows
```

#### STEP 3: Issue Categorization and Scoring
```bash
# Categorize each issue found
For each issue:
    Assign category: UCS_PATTERN_VIOLATION | RUST_BEST_PRACTICE |
                    CONNECTOR_PATTERN | CODE_QUALITY | TESTING_GAP |
                    DOCUMENTATION | PERFORMANCE | SECURITY

    Assign severity: CRITICAL | WARNING | SUGGESTION

    Check if exists in feedback.md:
        IF exists: Reference feedback ID (e.g., UCS-001, ANTI-001, SEC-001)
        IF new: Prepare to add to feedback.md with appropriate semantic prefix

# Count issues by severity
critical_count = [count of CRITICAL issues]
warning_count = [count of WARNING issues]
suggestion_count = [count of SUGGESTION issues]

# Calculate quality score
quality_score = 100 - (critical_count × 20) - (warning_count × 5) - (suggestion_count × 1)

# Determine status
IF quality_score < 60:
    status = "BLOCKED"
    blocking_reason = "Critical quality issues must be fixed"
ELIF quality_score < 80:
    status = "PASS WITH WARNINGS"
ELSE:
    status = "PASS"
```

#### STEP 4: Generate Review Report
```bash
# Use template from guides/quality/quality_review_template.md
# OR use template from top of guides/feedback.md

# Fill in all template sections:
1. Overall Quality Score: [calculated score]/100
2. Status: PASS | PASS WITH WARNINGS | BLOCKED
3. Issue Summary table with counts
4. Critical Issues section (if any)
   - For each critical issue:
     - Issue title and description
     - Code example (wrong and correct)
     - Why it's critical
     - How to fix (step-by-step)
     - References to feedback.md or patterns

5. Warning Issues section (if any)
   - For each warning:
     - Problem description
     - Current code
     - Recommended improvement
     - Impact explanation

6. Suggestions section (if any)
   - For each suggestion:
     - What could be improved
     - Benefit of improvement

7. Success Patterns section
   - Document what was done well
   - Identify reusable patterns

8. Quality Metrics checklist
   - Mark each compliance item as ✅ or ❌

9. Decision & Next Steps
   - Clear decision: APPROVE | APPROVE WITH WARNINGS | BLOCK
   - List required actions (if any)
   - List optional actions
   - Estimate fix time

10. Knowledge Base Updates
    - List new patterns to add
    - List existing patterns observed
```

#### STEP 5: Decision Making
```bash
# Make blocking decision based on quality score

IF status == "BLOCKED":
    Action: Do not proceed to next phase
    Reason: Quality score < 60 indicates critical issues
    Required: Implementer must fix critical issues
    Next: Re-run quality review after fixes

IF status == "PASS WITH WARNINGS":
    Action: Allow progression to next phase
    Reason: Quality score 60-79, functional but suboptimal
    Recommended: Fix warnings before final validation
    Note: Document warnings in review report

IF status == "PASS":
    Action: Approve progression to next phase
    Reason: Quality score ≥ 80, good quality
    Bonus: Document success patterns if score ≥ 95
```

#### STEP 6: Update Knowledge Base
```bash
# Update guides/feedback.md with new learnings

For each new pattern discovered:
    1. Choose appropriate feedback ID from ranges
    2. Fill feedback entry template
    3. Add to correct section in feedback.md
    4. Document lessons learned

For each existing pattern observed:
    1. Find feedback entry in feedback.md
    2. Increment frequency count
    3. Update if additional insights gained

For successful patterns:
    1. Add to Section 6: Success Patterns
    2. Provide code examples
    3. Explain why it's excellent
    4. Note reusability potential
```

#### STEP 7: Completion Confirmation
```bash
# Report comprehensive quality review completion

Report format:
"COMPREHENSIVE QUALITY REVIEW COMPLETED: [ConnectorName]
 Overall Quality Score: [score]/100
 Status: [PASS | PASS WITH WARNINGS | BLOCKED]

 Issue Breakdown:
   Critical Issues: [count]
   Warning Issues: [count]
   Suggestions: [count]

 Flows Reviewed: Authorize, PSync, Capture, Refund, RSync, Void
 Decision: [APPROVE FOR COMPLETION | BLOCK UNTIL FIXES APPLIED]"

# Provide comprehensive review report to user
Display: Complete quality review report covering all flows

# If blocked
IF status == "BLOCKED":
    Provide: Detailed fix instructions for each critical issue across all flows
    Offer: Auto-fix commands if available
    Note: Connector cannot be marked as complete until issues are resolved
    Required: Re-run quality review after fixes

# If passed
IF status != "BLOCKED":
    Confirm: All quality gates passed - connector ready for completion
    Note: Optional improvements if warnings or suggestions exist
    Approve: Workflow can proceed to completion report generation
```

## COMPREHENSIVE QUALITY REVIEW CHECKLIST

### Overall UCS Compliance
- [ ] All flows use ConnectorIntegrationV2 (not ConnectorIntegration)
- [ ] RouterDataV2 used throughout all flows (not RouterData)
- [ ] domain_types imports used everywhere (not hyperswitch_*)
- [ ] Connector struct uses generic `<T: PaymentMethodDataTypes>`
- [ ] All trait bounds properly defined

### Foundation Structure
- [ ] ConnectorCommon trait properly implemented
- [ ] Authentication type structure correct
- [ ] Error response structure defined
- [ ] Currency unit configuration appropriate
- [ ] Base URL configuration method correct

### All Flows Implementation
- [ ] Authorize flow complete and follows pattern_authorize.md
- [ ] PSync flow complete and follows pattern_psync.md
- [ ] Capture flow complete and follows pattern_capture.md
- [ ] Refund flow complete and follows pattern_refund.md
- [ ] RSync flow complete and follows pattern_rsync.md
- [ ] Void flow complete and follows pattern_void.md

### Macro Pattern Implementation (All Flows)
- [ ] All flows defined in create_all_prerequisites! macro
- [ ] All flows implemented with macro_connector_implementation! (no manual impl)
- [ ] Flow definitions include correct router_data types
- [ ] Request/Response type naming follows convention: {ConnectorName}{FlowName}{Request|Response}
- [ ] Generic types used appropriately (<T> for flows needing payment method data)
- [ ] HTTP methods match API documentation
- [ ] Content types correct (Json, FormData, FormUrlEncoded, or omitted)
- [ ] member_functions in create_all_prerequisites! include build_headers and connector_base_url methods
- [ ] Amount converter configured correctly in create_all_prerequisites!

### Transformers Quality (All Flows)
- [ ] Request transformers complete and correct for all flows
- [ ] Response transformers complete and correct for all flows
- [ ] Status mapping comprehensive and consistent across flows
- [ ] Error handling proper and complete throughout
- [ ] Payment method support adequate

### Code Quality (Holistic)
- [ ] No code duplication across flows
- [ ] Consistent naming conventions throughout
- [ ] Clear separation of concerns
- [ ] Adequate modularity and reusability
- [ ] Performance optimized
- [ ] Security reviewed

### Cross-Flow Consistency
- [ ] All flows follow same authentication pattern
- [ ] Status mapping consistent across related flows
- [ ] Error handling patterns uniform
- [ ] Transformer logic reuse where applicable
- [ ] Similar operations implemented similarly

### Final Validation
- [ ] Cargo build succeeds without errors
- [ ] No critical UCS pattern violations
- [ ] No security vulnerabilities
- [ ] Documentation adequate
- [ ] Ready for production use

## BLOCKING CRITERIA

Quality Guardian MUST block progression if:

### Automatic Blocks (Quality Score < 60)
- Critical UCS pattern violations exist
- Security vulnerabilities present
- Will cause runtime failures
- Breaks UCS architectural requirements
- Makes code unmaintainable

### Specific Blocking Issues
1. **Wrong UCS Types Used**
   - Using RouterData instead of RouterDataV2
   - Using ConnectorIntegration instead of ConnectorIntegrationV2
   - Importing from hyperswitch_* instead of domain_types

2. **Missing Mandatory Implementations**
   - Required trait methods not implemented
   - Critical flow logic missing
   - Essential error handling absent

3. **Security Issues**
   - Credentials exposed in code
   - Missing input validation
   - Unsafe operations

4. **Architecture Violations**
   - Non-generic connector struct
   - Wrong import paths
   - Incorrect trait implementations

## ERROR HANDLING

### If Blocking Issues Found
```bash
1. Document each critical issue in detail
2. Provide exact file location and line number
3. Show current problematic code
4. Show correct implementation
5. Explain why it's critical
6. Provide step-by-step fix instructions
7. Estimate time to fix
8. Offer auto-fix if available
```

### If Quality Review Fails to Complete
```bash
1. Check guides/feedback.md exists and is readable
2. Check guides/quality/ directory structure
3. Verify files to review exist
4. Report error to main workflow controller
5. Request manual intervention if needed
```

### If Unsure About Severity
```bash
Default severity assignments:
- UCS pattern violations: CRITICAL
- Security issues: CRITICAL
- Code quality issues: WARNING
- Documentation gaps: SUGGESTION
- Performance issues: WARNING
- Test gaps: SUGGESTION
```

## QUALITY SCORING ALGORITHM

### Calculation
```
quality_score = 100 - (critical_count × 20) - (warning_count × 5) - (suggestion_count × 1)
```

### Thresholds
```
95-100: Excellent ✨ - Auto-pass, document success patterns
80-94:  Good ✅ - Pass with minor notes
60-79:  Fair ⚠️ - Pass with warnings, recommend fixes
40-59:  Poor ❌ - Block with required fixes
0-39:   Critical 🚨 - Block immediately, requires rework
```

### Example Calculations
```
Example 1: Clean implementation
- Critical: 0 × 20 = 0
- Warning: 1 × 5 = 5
- Suggestion: 3 × 1 = 3
Score: 100 - 0 - 5 - 3 = 92 (Good ✅)

Example 2: Issues found
- Critical: 2 × 20 = 40
- Warning: 3 × 5 = 15
- Suggestion: 5 × 1 = 5
Score: 100 - 40 - 15 - 5 = 40 (Poor ❌ - BLOCK)
```

# ============================================================================
# 🛡️ ERROR HANDLING AND UCS COMPLIANCE
# ============================================================================

## MANDATORY ERROR HANDLING RULES

### COMPILATION ERROR RESOLUTION
- **When cargo build fails**: Analyze error message completely
- **UCS Convention Fixes**: Ensure RouterDataV2, ConnectorIntegrationV2, domain_types usage
- **Type Error Fixes**: Verify generic types and trait implementations
- **Import Error Fixes**: Use correct domain_types imports
- **Syntax Error Fixes**: Follow Rust syntax rules exactly

### ERROR TYPE USAGE (CRITICAL)
- **Error types are split by phase**: request phase uses `IntegrationError`, response phase uses `ConnectorError`
- **ALWAYS use specific NotSupported errors** for unsupported payment methods:
  ```rust
  // CORRECT - Specific error message (request phase)
  Err(errors::IntegrationError::NotSupported {
      message: "Google Pay is not supported".to_string(),
      connector: "stripe",
      context: Default::default(),
  })

  // WRONG - Generic error
  Err(errors::IntegrationError::NotSupported {
      message: "Payment method not supported".to_string(),
      connector: "stripe",
      context: Default::default(),
  })
  ```
- **Specify exactly what is not supported**: Don't use vague error messages
- **Use proper error types** from the errors module for all error cases
- **Match error types to the situation**:
  - `IntegrationError::NotSupported` for unsupported features/methods (request phase)
  - `IntegrationError::MissingRequiredField` for missing required fields (request phase)
  - `ConnectorError::ResponseDeserializationFailed` for parsing errors (response phase)
  - `ConnectorError::InvalidData` for response data validation failures

### UCS COMPLIANCE VALIDATION
- **RouterDataV2**: NEVER use RouterData, always RouterDataV2
- **ConnectorIntegrationV2**: NEVER use ConnectorIntegration, always ConnectorIntegrationV2
- **Domain Types**: NEVER import from hyperswitch_domain_models, always domain_types
- **Generic Patterns**: Always use ConnectorName<T> where T: PaymentMethodDataTypes
- **Flow Independence**: Each flow must compile independently

### RETRY LOGIC
- **Build Failures**: Retry up to 3 times after fixing errors
- **Script Failures**: Analyze error, fix prerequisites, retry once
- **Pattern Violations**: Fix UCS compliance issues, retry build
- **Critical Failures**: If unable to resolve after retries, escalate with detailed error report

# ============================================================================
# 🧹 CODE CLEANLINESS AND FIELD USAGE RULES
# ============================================================================

## FIELD USAGE BEST PRACTICES (CRITICAL)

### REMOVE UNUSED FIELDS
- **NEVER keep fields that are always None**: If a field is hardcoded to None, remove it completely
  ```rust
  // WRONG - Unnecessary field
  pub struct StripeAuthorizeRequest<T> {
      pub amount: i64,
      pub currency: String,
      pub unused_field: Option<String>,  // Always set to None - REMOVE THIS
  }

  impl TryFrom<...> for StripeAuthorizeRequest<T> {
      fn try_from(item: ...) -> Result<Self, Self::Error> {
          Ok(Self {
              amount: item.amount,
              currency: item.currency,
              unused_field: None,  // ❌ WRONG - Remove this field entirely
          })
      }
  }

  // CORRECT - Clean struct without unused fields
  pub struct StripeAuthorizeRequest<T> {
      pub amount: i64,
      pub currency: String,
  }

  impl TryFrom<...> for StripeAuthorizeRequest<T> {
      fn try_from(item: ...) -> Result<Self, Self::Error> {
          Ok(Self {
              amount: item.amount,
              currency: item.currency,
          })
      }
  }
  ```

### QUESTION EVERY FIELD
- **Before adding a field, ask**: Is this field actually used by the connector API?
- **Check the API documentation**: Only include fields that the connector expects
- **Remove optional fields** that are never populated in transformers
- **Keep structs minimal**: Only include what's necessary for the API contract

### AVOID UNNECESSARY OPTIONALS
- **Don't make fields Optional unless required**:
  ```rust
  // WRONG - Unnecessary Optional
  pub struct Request {
      pub amount: Option<i64>,  // If amount is always present, don't use Option
  }

  // CORRECT - Non-optional when always present
  pub struct Request {
      pub amount: i64,
  }
  ```
- **Use Option only when**:
  - The field is truly optional per the connector API spec
  - The field may not be available in certain payment flows
  - The connector explicitly allows the field to be omitted

## STATUS MAPPING RULES (CRITICAL)

### NEVER HARDCODE STATUS VALUES
- **ALWAYS derive status from connector response**, never assume or hardcode:
  ```rust
  // WRONG - Hardcoded status
  impl TryFrom<ResponseRouterData<StripePaymentResponse, ...>> for RouterDataV2<...> {
      fn try_from(item: ResponseRouterData<...>) -> Result<Self, Self::Error> {
          Ok(Self {
              status: AttemptStatus::Charged,  // ❌ WRONG - Hardcoded!
              ..item.data
          })
      }
  }

  // CORRECT - Status derived from response
  impl TryFrom<ResponseRouterData<StripePaymentResponse, ...>> for RouterDataV2<...> {
      fn try_from(item: ResponseRouterData<...>) -> Result<Self, Self::Error> {
          Ok(Self {
              status: map_stripe_status_to_attempt_status(&item.response.status),  // ✅ CORRECT
              ..item.data
          })
      }
  }
  ```

### CREATE COMPREHENSIVE STATUS MAPPING FUNCTIONS
- **Map ALL possible status values** from the connector API:
  ```rust
  fn map_connector_status_to_attempt_status(
      status: &ConnectorStatus,
  ) -> common_enums::AttemptStatus {
      match status {
          ConnectorStatus::Succeeded => common_enums::AttemptStatus::Charged,
          ConnectorStatus::Pending => common_enums::AttemptStatus::Pending,
          ConnectorStatus::Failed => common_enums::AttemptStatus::Failure,
          ConnectorStatus::Cancelled => common_enums::AttemptStatus::Voided,
          ConnectorStatus::RequiresAction => common_enums::AttemptStatus::AuthenticationPending,
          // Map ALL statuses from connector API documentation
      }
  }
  ```
- **Reference the connector API docs** to identify all possible status values
- **Handle all enum variants**: Ensure exhaustive matching for status enums

## VALIDATION BEST PRACTICES

### EXPLAIN VALIDATION PURPOSE
- **Add comments** explaining why a validation exists:
  ```rust
  // CORRECT - Validation with explanation
  // Stripe requires amount to be at least $0.50 USD or equivalent
  if amount < 50 {
      return Err(errors::IntegrationError::InvalidData {
          message: "Amount must be at least 50 cents".to_string(),
          context: Default::default(),
      });
  }
  ```

### AVOID UNNECESSARY VALIDATIONS
- **Only validate when required** by the connector API specification
- **Don't add defensive validations** that aren't enforced by the connector
- **Remove validations that add complexity** without clear benefit:
  ```rust
  // WRONG - Unnecessary validation
  if currency.len() != 3 {
      return Err(...);  // If connector doesn't require this, don't validate
  }

  // CORRECT - Only validate what connector requires
  // Just pass the currency to the connector; let it handle validation
  ```

### VALIDATION CHECKLIST
- **Is this validation required by the connector API?** Check documentation
- **Does this validation prevent actual errors?** Don't validate speculatively
- **Is the error message clear and actionable?** Explain what's wrong and how to fix it

## STRUCT CLEANLINESS CHECKLIST

Before finalizing any request/response struct, verify:
- [ ] Every field is used (not hardcoded to None)
- [ ] Fields match the connector API documentation exactly
- [ ] Optional fields are only Optional when truly optional
- [ ] No defensive fields "just in case" - only what's needed
- [ ] Field names match connector API or follow clear naming conventions
- [ ] Serde attributes properly configured for API requirements

# ============================================================================
# 🎯 VALIDATION GATES AND PROGRESS TRACKING
# ============================================================================

## VALIDATION GATES (MANDATORY CHECKPOINTS)

### GATE 1: TECH SPEC VALIDATION
- ✅ Tech spec file exists in grace/rulesbook/codegen/references/{connector_name}/technical_specification.md *(after PHASE 1.0 Discovery & Recovery has run)*
- ✅ Tech spec contains connector name and base URL
- ✅ Tech spec lists supported payment methods
- ✅ Tech spec defines required flows
- **GATE FAILURE**: Cannot proceed without valid tech spec. GATE fails only if PHASE 1.0 recovery (Links Agent → Tech Spec Agent) also failed to produce the spec. Include the failing subagent's reason in the gate-failure report.

### GATE 2: FOUNDATION COMPLETION
- ✅ add_connector.sh executed successfully
- ✅ All template files created correctly
- ✅ cargo build passes without errors
- ✅ UCS conventions validated
- **GATE FAILURE**: Cannot proceed to flow implementation

### GATE 3: FLOW COMPLETION (PER FLOW)
- ✅ Flow pattern read and understood
- ✅ Implementation plan generated
- ✅ ConnectorIntegrationV2 trait implemented
- ✅ Request/response transformers created
- ✅ cargo build passes for this flow
- **GATE FAILURE**: Cannot proceed to next flow

### GATE 4: FINAL VALIDATION
- ✅ All flows implemented successfully
- ✅ Final cargo build passes
- ✅ No compilation errors or warnings
- ✅ All UCS patterns followed correctly
- **GATE FAILURE**: Implementation incomplete

## PROGRESS TRACKING FORMAT

### PHASE COMPLETION TRACKING
```
[✅ PHASE COMPLETED] Phase Name: Detailed description of what was accomplished
- Specific files created/modified
- Key implementations added
- Validation results
- Next phase prerequisites met
```

### FLOW COMPLETION TRACKING  
```
[✅ FLOW COMPLETED] {FlowName}: Implemented {specific_details}
- Files modified: {list_of_files}
- Methods implemented: {list_of_methods}
- Payment methods supported: {list_of_payment_methods}
- Build status: SUCCESSFUL
- Ready for next flow: YES
```

### ERROR TRACKING
```
[❌ ERROR ENCOUNTERED] {Phase/Flow}: {Error description}
- Error type: {compilation/script/validation}
- Error message: {detailed_error_message}
- Resolution attempted: {what_was_tried}
- Resolution status: {resolved/escalated}
```

# ============================================================================
# 🚨 CRITICAL EXECUTION RULES
# ============================================================================

## MODEL-INDEPENDENT TOOL USAGE POLICY

**THIS SECTION APPLIES TO ALL MODELS - NO EXCEPTIONS**

Whether you are running on kimi-latest, glm-latest, opus, sonnet, haiku, or any other model, the following
rules are MANDATORY and NON-NEGOTIABLE:

### CONTROLLER TOOL PERMISSIONS

**ALLOWED TOOLS** (Use these yourself):
- `Task` - For delegating work to subagents
- `TaskOutput` - For retrieving results from background subagents

**FORBIDDEN TOOLS** (Do NOT use - subagents must use these):
- `Read` - Subagent should read files
- `Write` - Subagent should write files
- `Edit` - Subagent should edit files
- `Glob` - Subagent should find files
- `Grep` - Subagent should search content
- `Bash` - Subagent should execute commands
- `WebSearch` - Subagent should do web searches
- `WebFetch` - Subagent should fetch web content
- `NotebookEdit` - Subagent should edit notebooks
- `AskUserQuestion` - Subagent should ask user questions
- `SlashCommand` - Subagent should execute slash commands
- `Skill` - Subagent should invoke skills
- `ExitPlanMode` - Subagent should exit plan mode
- `EnterPlanMode` - Subagent should enter plan mode
- `TodoWrite` - Subagent should manage todos
- `KillShell` - Subagent should kill shells
- `Any other tool` - Subagent should use it

### WHY THIS RESTRICTION EXISTS

1. **Consistency**: Same workflow across all models
2. **Scalability**: More capable models can still benefit from the workflow
3. **Separation of Concerns**: Clear distinction between controller and implementer
4. **Auditability**: Easier to track who did what
5. **Debugging**: Issues are isolated to specific subagents

### WHAT HAPPENS IF YOU VIOLATE THIS

If you use a forbidden tool directly:
- You are violating the workflow design
- The workflow becomes model-dependent
- Benefits of the subagent architecture are lost
- The implementation may not follow UCS patterns correctly

## MANDATORY EXECUTION PRINCIPLES

### 1. SEQUENTIAL EXECUTION ONLY
- **NEVER** run phases in parallel
- **NEVER** skip validation gates
- **NEVER** proceed with errors unresolved
- **ALWAYS** wait for subagent completion before continuing

### 2. SUBAGENT DELEGATION RULES
- **CLEARLY STATE** when delegating to subagent
- **WAIT FOR** explicit completion confirmation
- **VALIDATE** subagent work before proceeding
- **ESCALATE** if subagent fails after retries

### 3. BUILD VALIDATION REQUIREMENTS
- **SUBAGENT MUST** execute cargo build after each major step
- **SUBAGENT MUST** resolve all compilation errors immediately
- **NEVER** proceed with build failures
- **DOCUMENT** build success in progress tracking

### 4. UCS CONVENTION ENFORCEMENT
- **SUBAGENT MUST** validate UCS patterns at each step
- **SUBAGENT MUST** correct non-UCS code immediately
- **SUBAGENT MUST** reference existing UCS connectors for patterns
- **SUBAGENT MUST** maintain consistency with UCS architecture

### 5. ERROR ESCALATION PROTOCOL
- **ATTEMPT** resolution following documented procedures
- **RETRY** with fixes up to specified limits
- **ESCALATE** with detailed error report if unable to resolve
- **NEVER** ignore or skip errors

# ============================================================================
# 📋 EXAMPLE EXECUTION WORKFLOW
# ============================================================================

## SAMPLE EXECUTION SEQUENCE

When user executes: "integrate {ConnectorName} using grace/rulesbook/codegen/.gracerules"

### EXPECTED EXECUTION:
```
🎯 MAIN WORKFLOW CONTROLLER: Starting deterministic workflow for stripe

📖 PHASE 1: TECH SPEC VALIDATION
[✅ COMPLETED] Read tech spec from references/stripe/
[✅ COMPLETED] Validated tech spec completeness  
[✅ COMPLETED] Extracted connector requirements

🔧 PHASE 2: FOUNDATION SETUP
[🤖 DELEGATING] To Foundation Setup Subagent...
[✅ COMPLETED] Foundation Setup Subagent reported completion
[✅ VALIDATED] Cargo build successful

📚 PHASE 2.5: MACRO PATTERN REFERENCE STUDY
[✅ COMPLETED] Read guides/patterns/macro_patterns_reference.md
[✅ COMPLETED] Read guides/patterns/flow_macro_guide.md
[✅ COMPLETED] Read template-generation/macro_templates.md
[✅ VALIDATED] Understood macro usage patterns and conventions

🔄 PHASE 3: FLOW IMPLEMENTATION  
[🤖 DELEGATING] To Authorize Flow Subagent...
[✅ COMPLETED] Authorize Flow Subagent reported completion
[🤖 DELEGATING] To PSync Flow Subagent...
[✅ COMPLETED] PSync Flow Subagent reported completion
[🤖 DELEGATING] To Capture Flow Subagent...
[✅ COMPLETED] Capture Flow Subagent reported completion
[🤖 DELEGATING] To Refund Flow Subagent...
[✅ COMPLETED] Refund Flow Subagent reported completion
[🤖 DELEGATING] To RSync Flow Subagent...
[✅ COMPLETED] RSync Flow Subagent reported completion
[🤖 DELEGATING] To Void Flow Subagent...
[✅ COMPLETED] Void Flow Subagent reported completion

🛡️ PHASE 4: FINAL VALIDATION AND QUALITY REVIEW
[✅ COMPLETED] Final cargo build successful
[✅ COMPLETED] All flows compile successfully
[🛡️ QUALITY GATE] Delegating to Quality Guardian Subagent...
[🔍 REVIEWING] Comprehensive code quality analysis across all flows...
[✅ QUALITY REVIEW COMPLETED]
    Overall Quality Score: 91/100 - PASS (Excellent)
    Critical Issues: 0
    Warnings: 2 (minor code style improvements)
    Suggestions: 7 (documentation enhancements)
    Decision: APPROVED
[✅ ALL QUALITY GATES PASSED]

🎉 WORKFLOW COMPLETED: Stripe connector fully implemented with high quality (Score: 91/100)
```

## FAILURE HANDLING EXAMPLES:

### Example 1: Build Failure
```
🔧 PHASE 2: FOUNDATION SETUP
[🤖 DELEGATING] To Foundation Setup Subagent...
[❌ ERROR] Foundation Setup failed: cargo build compilation error
[🔧 RESOLVING] Foundation Setup Subagent fixing compilation errors...
[✅ RESOLVED] Compilation errors fixed, retrying build...
[✅ COMPLETED] Foundation Setup Subagent reported completion
```

### Example 2: Quality Gate Failure
```
🛡️ PHASE 4: FINAL VALIDATION AND QUALITY REVIEW
[✅ COMPLETED] Final cargo build successful
[✅ COMPLETED] All flows compile successfully
[🛡️ QUALITY GATE] Delegating to Quality Guardian Subagent...
[🔍 REVIEWING] Comprehensive code quality analysis across all flows...
[❌ QUALITY REVIEW BLOCKED]
    Overall Quality Score: 45/100 - BLOCKED
    Critical Issues: 3
      - CRITICAL-1: Using RouterData instead of RouterDataV2 in transformers.rs:25
      - CRITICAL-2: Missing domain_types import in connector.rs:5
      - CRITICAL-3: Non-generic connector struct in connector.rs:15
    Warnings: 5
    Suggestions: 8
    Decision: BLOCKED UNTIL FIXES APPLIED

[❌ WORKFLOW BLOCKED] Quality score below threshold (45 < 60)
[🔧 ACTION REQUIRED] Fix critical issues and re-run quality review

Developer fixes critical issues...

[🔄 RE-RUNNING] Quality review after fixes...
[✅ QUALITY REVIEW COMPLETED]
    Overall Quality Score: 88/100 - PASS
    Critical Issues: 0
    Warnings: 2
    Suggestions: 5
    Decision: APPROVED
[✅ ALL QUALITY GATES PASSED]

🎉 WORKFLOW COMPLETED: Connector implemented with good quality (Score: 88/100)
```

# ============================================================================
# 🎯 ACTIVATION TRIGGER
# ============================================================================

This workflow activates when the user provides a command matching this pattern:
- "integrate {ConnectorName} using grace/rulesbook/codegen/.gracerules"
- "integrate {ConnectorName} connector using grace/rulesbook/codegen/.gracerules"

## ACTIVATION CHECKLIST (Model-Independent)

Upon activation, REGARDLESS of which model you are running on:

1. ✅ Confirm you are in CONTROLLER mode only
2. ✅ Verify you will ONLY use Task tool for delegation
3. ✅ Verify you will NOT use Read/Write/Edit/Glob/Grep/Bash directly
4. ✅ Begin timeline initialization
5. ✅ Delegate first phase to appropriate subagent

## IMMEDIATE ACTIONS UPON ACTIVATION

Do NOT read files yourself. Do NOT execute commands yourself. Do NOT implement code yourself.

Instead, immediately begin with:
1. Initialize timeline tracker: `timeline = SimpleTimeline(connector_name="{connector_name}")`
2. DELEGATE to Cypress Validation Subagent for Phase 0
3. Wait for subagent completion before proceeding to next phase
4. Follow the deterministic sequence exactly as specified

## FINAL REMINDERS

NO DEVIATION FROM THIS WORKFLOW IS PERMITTED.
ALL STEPS MUST COMPLETE SUCCESSFULLY BEFORE PROCEEDING.
SUBAGENTS MUST CONFIRM COMPLETION BEFORE NEXT PHASE BEGINS.

YOU ARE THE COORDINATOR, NOT THE IMPLEMENTER.
THE SUBAGENTS DO THE ACTUAL WORK.

This applies to ALL models: kimi-latest, glm-latest, opus, sonnet, haiku, or any other.