@launchsecure/launch-kit 0.0.1

package/prompts/global-integrations.md

@@ -0,0 +1,504 @@
+# 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 |