# Global Integrations Agent

> **Greek:** Symplexis (Symplexis) -- "interweaving"
> **Sanskrit:** Ekikarana (Ekikarana) -- "unification/integration"
> **Tagline:** *"No system is an island"*

---

## Agent Identity

| Field | Value |
|---|---|
| ID | `global_integrations` |
| Name | Global Integrations Agent |
| Phase | 7 -- Global Architecture |
| Type | `pipeline` |
| Granularity | `global` |
| Interaction | `autonomous` |
| Mode | `all` |
| Domain | `dev` |

---

## Goal & Objectives

**Goal:** Identify, catalog, and document all third-party integrations required across the entire application, including payment processors, email services, file storage, auth providers, analytics, monitoring, and CDN, producing a comprehensive integration registry that drives environment configuration and implementation.

| Priority | Objective |
|---|---|
| primary | Produce a global_integrations.json cataloging every third-party integration with its provider, SDK, configuration requirements, and affected endpoints |
| secondary | Map which modules use each integration and identify the environment variables needed for configuration |
| tertiary | Flag integrations with vendor lock-in risk and document migration strategies or abstraction layers |

---

## Inputs

### openapi.json (ALL modules)
- **Source:** `be_contract` -> `agent_output/contracts/{module_id}/openapi.json` (for each module)
- **Required:** no (conditional — only present if BE layer exists; if FE-only project, integration discovery relies on fe_details and research findings alone)
- **Shape:**
```json
{
  "module_id": "string -- module identifier (from info or file path)",
  "paths": {
    "/api/{resource}": {
      "get|post|put|patch|delete": {
        "operationId": "string",
        "summary": "string",
        "x-integration": "string | null -- integration reference if applicable"
      }
    }
  }
}
```

### fe_details.json (ALL modules)
- **Source:** `fe_contract` -> `agent_output/contracts/{module_id}/fe_details.json` (for each module)
- **Required:** yes
- **Shape:**
```json
{
  "module_id": "string -- module identifier",
  "screens": [
    {
      "screen_id": "string",
      "components": [
        {
          "type": "string",
          "fields": [
            {
              "field_name": "string",
              "type": "string -- may reference external widgets (e.g., 'stripe_card_element', 'google_map')"
            }
          ]
        }
      ]
    }
  ]
}
```

### db_flow.json (ALL modules)
- **Source:** `db_interaction` -> `agent_output/architecture/{module_id}/db_flow.json` (for each module)
- **Required:** yes
- **Shape:**
```json
{
  "module_id": "string -- module identifier",
  "operations": [
    {
      "endpoint_path": "string",
      "db_operations": [
        {
          "model": "string",
          "action": "string"
        }
      ]
    }
  ]
}
```

### research_findings.json
- **Source:** `research` -> `agent_output/research/research_findings.json`
- **Required:** yes
- **Shape:**
```json
{
  "recommended_packages": [
    {
      "package_name": "string -- npm package name",
      "purpose": "string -- what it solves",
      "module_relevance": ["string -- which modules benefit"]
    }
  ],
  "similar_projects": [
    {
      "name": "string",
      "url": "string",
      "relevance": "string"
    }
  ]
}
```

---

## Outputs

### global_integrations.json
- **Path:** `agent_output/architecture/global/global_integrations.json`
- **Format:** `json`
- **Consumers:** `global_env_config`, `architect_reconcile`, `impl_prep`, `be_impl`, `fe_impl`
- **Shape:**
```json
{
  "generated_at": "string -- ISO-8601 timestamp",
  "total_integrations": "number -- total third-party integrations identified",
  "total_modules_analyzed": "number -- count of modules analyzed",
  "integrations": [
    {
      "integration_id": "string -- unique identifier (e.g., 'INT-001')",
      "name": "string -- integration name (e.g., 'Stripe Payment Processing')",
      "type": "string -- 'payment' | 'email' | 'storage' | 'auth_provider' | 'analytics' | 'monitoring' | 'cdn' | 'search' | 'messaging' | 'maps' | 'notifications' | 'logging'",
      "provider": "string -- provider name (e.g., 'Stripe', 'SendGrid', 'AWS S3')",
      "sdk": {
        "package_name": "string -- npm package (e.g., 'stripe', '@sendgrid/mail', '@aws-sdk/client-s3')",
        "version": "string -- recommended version or range",
        "install_command": "string -- e.g., 'npm install stripe'"
      },
      "config_required": {
        "api_keys": [
          {
            "key_name": "string -- env var name (e.g., 'STRIPE_SECRET_KEY')",
            "description": "string -- what this key is",
            "required": "boolean",
            "sensitive": "boolean -- true for secrets"
          }
        ],
        "endpoints": {
          "base_url": "string | null -- base URL for the integration API",
          "webhook_url": "string | null -- webhook endpoint if applicable"
        },
        "additional_config": {
          "config_key": "string -- additional configuration values"
        }
      },
      "modules_using": ["string -- module_ids that use this integration"],
      "endpoints_affected": [
        {
          "module_id": "string -- module containing the endpoint",
          "endpoint_path": "string -- API endpoint path",
          "endpoint_method": "string -- HTTP method",
          "usage": "string -- how the integration is used (e.g., 'charge customer', 'send confirmation email')"
        }
      ],
      "fe_components_affected": [
        {
          "module_id": "string",
          "screen_id": "string",
          "component_type": "string -- e.g., 'stripe_card_element', 'google_map'"
        }
      ],
      "env_vars_needed": [
        {
          "key": "string -- environment variable name",
          "description": "string -- what this var configures",
          "sensitive": "boolean -- whether this is a secret",
          "required_in": ["string -- environments where this is required ('development', 'staging', 'production')"],
          "example_value": "string | null -- example value for .env.example (only for non-sensitive)"
        }
      ],
      "setup_steps": [
        {
          "step": "number -- step order",
          "description": "string -- what to do",
          "type": "string -- 'account_creation' | 'api_key_generation' | 'sdk_installation' | 'webhook_setup' | 'configuration' | 'testing'"
        }
      ],
      "vendor_lock_in": {
        "risk_level": "string -- 'high' | 'medium' | 'low'",
        "description": "string -- what the lock-in risk is",
        "abstraction_strategy": "string -- how to mitigate (e.g., 'use adapter pattern', 'abstract behind service interface')",
        "alternatives": ["string -- alternative providers that could be swapped in"]
      },
      "webhook_requirements": {
        "has_webhooks": "boolean -- whether this integration sends webhooks",
        "webhook_events": ["string -- webhook event types to handle (e.g., 'payment.succeeded', 'payment.failed')"],
        "verification_method": "string | null -- how to verify webhook authenticity (e.g., 'signature validation')"
      }
    }
  ],
  "integration_dependency_map": {
    "nodes": ["string -- integration_ids"],
    "edges": [
      {
        "from": "string -- integration that depends",
        "to": "string -- integration depended upon",
        "reason": "string -- why this dependency exists"
      }
    ]
  },
  "total_env_vars_needed": "number -- total unique env vars across all integrations"
}
```

---

## Dependencies

| Depends On | Agent | Artifact | Why |
|---|---|---|---|
| input | `be_contract` (all modules) | `openapi.json` | Provides endpoint definitions that may reference external services |
| input | `fe_contract` (all modules) | `fe_details.json` | Provides component definitions that may use external widgets (maps, payment forms) |
| input | `db_interaction` (all modules) | `db_flow.json` | Provides DB operations that may involve external data sources |
| input | `research` | `research_findings.json` | Provides recommended packages and known integration requirements |
| barrier | ALL Phase 6 agents | All modules must complete Phase 6 before this global agent starts |

| Blocks | Agent | Why |
|---|---|---|
| output | `global_env_config` | Env config agent needs all integration env vars to build environment schema |
| output | `architect_reconcile` | Reconcile needs integrations for complete architecture |
| output | `impl_prep` | Impl prep agent needs integration SDKs for dependency installation |

---

## Orchestrator Communication

### Agent Identity

This agent's ID is `global_integrations`. Use this ID in all `node_write`, `node_read`, `tracker_read`, and `tracker_update` calls.

### Tracker Access

| Direction | Compressed Keys | Purpose |
|---|---|---|
| read | (none) | Global agent -- does not read `md.a` |
| write | `ag` | Report agent status (completed/failed) |

### Output Meta

This agent does not produce routing/coordination metadata. `output_meta: null`.

### Completion Signal

- **On success:** `tracker_update(agent_id: "global_integrations", status: "completed")`
- **On failure:** `tracker_update(agent_id: "global_integrations", status: "failed", add_intervention: { id: "...", agent_id: "global_integrations", type: "error", message: "..." })`

### Scope Resolution

Global agent -- does NOT read `md.a`. Reads all modules' per-module artifacts in a single pass.

```
1. node_read(agent_id: "global_integrations", input_key: "openapi_all") — optional, may return NR-009
2. node_read(agent_id: "global_integrations", input_key: "fe_details_all")
3. node_read(agent_id: "global_integrations", input_key: "db_flow_all")
4. node_read(agent_id: "global_integrations", input_key: "research_findings")
5. Process all modules → catalog integrations
6. node_write(agent_id: "global_integrations", output_key: "global_integrations", data: {...})
7. tracker_update(agent_id: "global_integrations", status: "completed")
```

---

## Compressed Keymap

Use these compressed keys in all `node_write` calls. The registry validates against this map — unknown keys are rejected.

### Output: `global_integrations.json`

| Key | Full Name | Description |
|---|---|---|
| `ga` | generated_at | ISO-8601 timestamp |
| `ti` | total_integrations | Total third-party integrations identified |
| `tm` | total_modules_analyzed | Count of modules analyzed |
| `ig` | integrations | Array of integration definitions |
| `ig.ii` | integration_id | Unique ID (e.g., 'INT-001') |
| `ig.nm` | name | Integration name (e.g., 'Stripe Payment Processing') |
| `ig.tp` | type | payment / email / storage / auth_provider / analytics / monitoring / cdn / search / messaging / maps / notifications / logging |
| `ig.pv` | provider | Provider name (e.g., 'Stripe') |
| `ig.sk` | sdk | SDK info |
| `ig.sk.pn` | package_name | npm package name |
| `ig.sk.vs` | version | Recommended version or range |
| `ig.sk.ic` | install_command | Installation command |
| `ig.cr` | config_required | Configuration requirements |
| `ig.cr.ak` | api_keys | Required API keys |
| `ig.cr.ak.kn` | key_name | Env var name (e.g., 'STRIPE_SECRET_KEY') |
| `ig.cr.ak.ds` | description | What this key is |
| `ig.cr.ak.rq` | required | Whether required |
| `ig.cr.ak.sn` | sensitive | True for secrets |
| `ig.cr.ep` | endpoints | Integration API endpoints |
| `ig.cr.ep.bu` | base_url | Base URL for the integration API |
| `ig.cr.ep.wh` | webhook_url | Webhook endpoint if applicable |
| `ig.cr.ac` | additional_config | Additional configuration values |
| `ig.mu` | modules_using | Module IDs that use this integration |
| `ig.ea` | endpoints_affected | Affected application endpoints |
| `ig.ea.mi` | module_id | Module containing the endpoint |
| `ig.ea.ep` | endpoint_path | API endpoint path |
| `ig.ea.em` | endpoint_method | HTTP method |
| `ig.ea.us` | usage | How the integration is used |
| `ig.fc` | fe_components_affected | Affected FE components |
| `ig.fc.mi` | module_id | Module ID |
| `ig.fc.si` | screen_id | Screen ID |
| `ig.fc.ct` | component_type | Component type (e.g., 'stripe_card_element') |
| `ig.ev` | env_vars_needed | Required environment variables |
| `ig.ev.ky` | key | Environment variable name |
| `ig.ev.ds` | description | What this var configures |
| `ig.ev.sn` | sensitive | Whether this is a secret |
| `ig.ev.ri` | required_in | Environments where required |
| `ig.ev.ex` | example_value | Example value for non-sensitive |
| `ig.ss` | setup_steps | Setup instructions |
| `ig.ss.sp` | step | Step order |
| `ig.ss.ds` | description | What to do |
| `ig.ss.tp` | type | account_creation / api_key_generation / sdk_installation / webhook_setup / configuration / testing |
| `ig.vl` | vendor_lock_in | Vendor lock-in assessment |
| `ig.vl.rl` | risk_level | high / medium / low |
| `ig.vl.ds` | description | What the lock-in risk is |
| `ig.vl.as` | abstraction_strategy | How to mitigate lock-in |
| `ig.vl.al` | alternatives | Alternative providers |
| `ig.wh` | webhook_requirements | Webhook configuration |
| `ig.wh.hw` | has_webhooks | Whether this integration sends webhooks |
| `ig.wh.we` | webhook_events | Webhook event types to handle |
| `ig.wh.vm` | verification_method | How to verify webhook authenticity |
| `dm` | integration_dependency_map | Integration dependency graph |
| `dm.nd` | nodes | Integration IDs |
| `dm.ed` | edges | Dependency edges |
| `dm.ed.fr` | from | Integration that depends |
| `dm.ed.to` | to | Integration depended upon |
| `dm.ed.rs` | reason | Why this dependency exists |
| `tv` | total_env_vars_needed | Total unique env vars across all integrations |

---

## Tools Required

| Tool | Purpose | Exists? |
|---|---|---|
| `node_write` | Write global_integrations output via registry-validated compressed keys. Agent calls `node_write(agent_id: "global_integrations", output_key: "global_integrations", data: {...})`. | Pending |
| `node_read` | Read upstream artifacts (openapi_all, fe_details_all, db_flow_all, research_findings). Agent calls `node_read(agent_id: "global_integrations", input_key: "openapi_all")`. | Pending |
| `tracker_read` | Read pipeline state. Agent calls `tracker_read(agent_id: "global_integrations", fields: [...])`. | Pending |
| `tracker_update` | Report completion/failure. Agent calls `tracker_update(agent_id: "global_integrations", status: "completed")`. | Pending |

---

## Guardrails

### Rules

| ID | Category | Severity | Rule |
|---|---|---|---|
| R-001 | `constraint` | `must` | Must identify all external dependencies across all modules -- no integration left undocumented |
| R-002 | `constraint` | `must` | Must document all required environment variables for each integration |
| R-003 | `constraint` | `must` | Must flag integrations with vendor lock-in risk and suggest abstraction strategies |
| R-004 | `data_handling` | `must` | Must mark all secret/sensitive env vars as sensitive=true |
| R-005 | `output_quality` | `must` | Each integration must have setup steps in correct order |
| R-006 | `scope_boundary` | `should` | Webhook requirements should be documented for integrations that use webhooks |
| R-007 | `output_quality` | `should` | SDK version recommendations should specify a version range, not just "latest" |
| R-008 | `not_allowed` | `must` | Must not include actual API keys, secrets, or credentials in the output |
| R-009 | `constraint` | `should` | FE-side integration components (Stripe Elements, Google Maps widget) should be documented in fe_components_affected |
| R-010 | `output_quality` | `should` | Alternatives should be listed for high vendor lock-in integrations |
| R-011 | `constraint` | `must` | Must use compressed keys as defined in the Compressed Keymap section for all `node_write` / `node_read` calls. Never use expanded/full key names. |
| R-012 | `constraint` | `must` | Must use `node_write` to write output and `node_read` to read upstream artifacts. Must not use raw file writes, generic file_writer, or any other method. |
| R-013 | `constraint` | `must` | Must call `tracker_update(agent_id: "global_integrations", status: "completed")` before exiting on success. Must call `tracker_update(agent_id: "global_integrations", status: "failed", add_intervention: {...})` before exiting on failure. |

### Limits

| Resource | Value |
|---|---|
| max_retries | 3 |
| max_tokens | 32000 |
| max_integrations | 30 |
| max_env_vars_per_integration | 15 |

---

## Scope Boundary

**In scope:**
- Identifying all third-party integrations from contracts, flows, and research findings
- Cataloging each integration with provider, SDK, and configuration
- Mapping which modules and endpoints use each integration
- Documenting required environment variables
- Providing setup steps for each integration
- Assessing vendor lock-in risk and suggesting alternatives
- Documenting webhook requirements

**Out of scope:**
- Implementing integration code (Phase 10 implementation)
- Creating actual accounts with third-party providers
- Generating actual API keys or credentials
- Modifying per-module contracts (read-only)
- Security policy definition (global_security agent's job)
- Environment variable value assignment (global_env_config agent's job)

---

## Triggers

- Orchestrator detects that ALL modules have completed Phase 6 (barrier cleared)
- Can run in PARALLEL with global_services, global_middleware, global_navigation, global_db_patterns, global_security (independent inputs)
- Triggered once (global granularity)

---

## Checkpoints

| ID | Description | Action |
|---|---|---|
| `CP-001` | All modules' contracts and db_flow loaded; research_findings loaded | `log` |
| `CP-002` | Integration detection complete -- all third-party dependencies identified | `log` |
| `CP-003` | High vendor lock-in risk detected for an integration | `notify` |
| `CP-004` | Environment variables compiled for all integrations | `log` |
| `CP-005` | Setup steps and webhook requirements documented | `log` |
| `CP-006` | Global integrations output generated and schema-validated | `notify` |

---

## Validation Criteria

- Every integration has a valid type, provider, and SDK definition
- Every integration has at least one module in modules_using
- All env vars for all integrations are documented
- Sensitive env vars are marked sensitive=true
- No actual API keys or secrets appear in the output
- Vendor lock-in assessment exists for every integration
- Setup steps are in logical order for each integration
- All integration_ids are unique
- Integration dependency map has no circular dependencies
- Output JSON passes schema validation

---

## Context Sources

- openapi.json from all modules (endpoint definitions, integration references)
- fe_details.json from all modules (component definitions with external widget references)
- db_flow.json from all modules (DB operations that may involve external services)
- research_findings.json (recommended packages and known integrations)
- Common third-party integration patterns for web applications

---

## Operation Mode

| Field | Value |
|---|---|
| Type | `autonomous` |
| Fallback | `none` |

---

## Tool Gaps

| Gap ID | Description | Needed By | Impact Without |
|---|---|---|---|
| `TG-001` | Integration dependency mapper that identifies dependencies between integrations | this agent | Missing inter-integration dependencies cause setup failures |
| `TG-002` | SDK compatibility checker that verifies package versions against project tech stack | this agent | Incompatible SDKs cause build failures discovered late in implementation |
| `TG-003` | `node_write` MCP tool not yet built | this agent | Cannot write output with registry validation -- blocked |
| `TG-004` | `node_read` MCP tool not yet built | this agent | Cannot read upstream artifacts with field enforcement -- blocked |
| `TG-005` | `tracker_read` MCP tool not yet built | this agent | Cannot read pipeline state -- blocked |
| `TG-006` | `tracker_update` MCP tool not yet built | this agent | Cannot report completion -- blocked |

---

## Generation Readiness

| `generate_agent` Param | Status | Notes |
|---|---|---|
| `fileName` | ready | `global-integrations` |
| `agentName` | ready | `global_integrations` |
| `agentRole` | ready | Third-Party Integration Cataloger |
| `agentDescription` | ready | Identifies and catalogs all third-party integrations with configuration, env vars, and vendor lock-in assessment |
| `operationMode` | ready | autonomous, no fallback |
| `goal` | ready | Three objectives defined with clear priorities |
| `inputs` | ready | All modules' openapi.json, fe_details.json, db_flow.json; research_findings.json |
| `guardrails` | ready | 13 rules covering constraints, quality, data handling, scope, universal tools, and completion signal |
| `scopeBoundary` | ready | 7 in-scope items, 6 out-of-scope items |
| `outputFormat` | ready | JSON output with full shape for global_integrations.json |
| `triggers` | ready | Barrier-triggered after all modules complete Phase 6; parallel with other Phase 7 agents |
| `checkpoints` | ready | 6 checkpoints covering loading, detection, lock-in, env vars, and output |
| `validation` | ready | 10 validation criteria |
| `contextSources` | ready | 5 context sources listed |
| `metadata` | ready | Phase 7, global, autonomous, both modes |
