integrate-module

name	integrate-module
description	Turn any external program into a Genesis module via structured discovery, connection mapping, config generation, and verification.
consumer	cc_foreground
phase	7
skill_type	workflow

Integrate Module

Turn any external program into a Genesis module. This is the standardized process for plugging a program into Genesis — whether it was built for Genesis or not.

Genesis is the nervous system. The program is the body. This skill builds the connection between them.

When to Use

• User says "integrate X into Genesis" or "make X a module"
• User wants to plug an external program, service, or tool into Genesis
• User wants Genesis to drive, monitor, or interact with an external system
• Ego session discovers a program worth integrating and proposes it

Input

One of:

• Running service URL (e.g., http://your-host:8080)
• Repository URL (e.g., github.com/user/repo)
• Local path (e.g., ~/my-tool/)
• Description (e.g., "a job automation tool running on my server")

Phase 1: Discovery

Goal: Understand what the program does, how it communicates, and what Genesis can connect to.

If running service:

1. Probe for health endpoints: /health, /api/health, /status, /
2. Probe for API documentation: /docs, /openapi.json, /swagger.json
3. If OpenAPI spec found: parse all endpoints, methods, parameters
4. If no spec: probe common REST patterns, check response shapes
5. Record: base URL, available endpoints, response formats, auth requirements

If repository:

1. Clone or read the source
2. Identify tech stack (language, framework, database, scheduler)
3. Find entry points: route definitions, CLI commands, main functions
4. Map API endpoints from source (FastAPI routes, Express handlers, etc.)
5. Identify configuration: env vars, config files, secrets needed
6. Check deployment method: Docker, systemd, kubernetes, manual
7. Record: full capability map from source

If description only:

1. Ask the user for more details: where does it run? how do you access it?
2. Attempt to locate the service or source based on what they share
3. Fall back to manual endpoint mapping with user guidance

Output of Phase 1:

A structured assessment:

Program: [name]
Location: [URL / path / host]
Tech Stack: [language, framework, DB]
Communication: [HTTP API / CLI / stdin / socket]
Endpoints Found: [count]
Auth Required: [yes/no, method]
Health Check: [endpoint, expected response]

Phase 2: Connection Mapping

Goal: Map every program capability to a Genesis module operation.

For each discovered endpoint or command:

1. What does it do? (read data, trigger action, modify state)
2. What parameters does it take?
3. What does it return?
4. Is it safe to call autonomously? (read-only vs. state-changing)
5. Should it be in the operations manifest?

Group operations by category:

• Health/Status — monitoring operations (always include)
• Data Retrieval — read-only queries (safe for autonomous use)
• Actions — state-changing operations (may need user approval)
• Admin — deployment, configuration, lifecycle (restricted)

Output of Phase 2:

Draft operations manifest (YAML format):

operations:
  health:
    method: GET
    path: /api/health
    description: "Check service health"
  # ... all discovered operations

Phase 3: Effort Assessment

Goal: Give the user an honest picture of what's needed.

Assess each dimension:

• Connectivity — Can Genesis reach the program? (network, auth, firewall)
• API Coverage — What % of the program's capabilities are API-accessible?
• Health Monitoring — Is there a health endpoint? Can we detect failures?
• Lifecycle — Can Genesis start/stop/restart the program? (SSH, systemd, k8s)
• Data Flow — Can Genesis read the program's data? Push data to it?
• Autonomy Potential — What can Genesis do without user approval?

Rate complexity:

• Simple (1 session): Program has HTTP API, health endpoint, clear operations. Genesis wraps it as-is. Career Agent was this level.
• Moderate (2-3 sessions): Program needs some adapter work. Maybe API gaps, authentication setup, or custom endpoint mapping.
• Complex (multi-session): Program needs code changes. Missing API for key capabilities, no health endpoint, custom IPC needed, authentication integration.

Be explicit: "This integration will take [estimate]. Here's why: [specific gaps]."

If complex, recommend incremental approach:

1. Start with health monitoring + basic queries (one session)
2. Add action operations (second session)
3. Add lifecycle management (third session)
4. Add deep bidirectional capabilities (ongoing)

Phase 4: Config Generation

Goal: Create the YAML module config and any needed adapter code.

1. Generate config/modules/[program-name].yaml:

   • name, type: external, description
   • IPC method and URL
   • Health check endpoint
   • Lifecycle commands (if SSH available)
   • Full operations manifest from Phase 2
   • Configurable fields (if applicable)

2. If the program needs custom adapter code beyond what ExternalProgramAdapter provides, create it in src/genesis/modules/[program-name]/.

3. Test the connection: verify health check passes.

Phase 5: Dashboard Setup

Goal: Make the module usable from the Genesis dashboard.

Verify:

• Module appears in Modules & Providers panel with EXTERNAL badge
• Description is populated from YAML
• Health status shows Connected/Disconnected
• IPC details visible (method, URL)
• Lifecycle commands available (if configured)
• Clicking the module opens a useful detail modal

If the program has unique data worth displaying, consider adding custom dashboard elements (follow-up, not blocking).

Phase 6: Verification

Goal: Prove the integration works end-to-end.

1. Health check: module_call("[name]", "health") returns healthy
2. Data query: Test a read-only operation via module_call
3. Action (if applicable): Test a state-changing operation
4. Dashboard: Module shows correct status, description, operations
5. Persistence: Restart bridge, verify module re-loads from YAML
6. Error handling: What happens when the program is unreachable?

Phase 7: Documentation

1. Update MEMORY.md with the new module entry
2. If the integration required non-obvious decisions, record them
3. Commit all changes via worktree, merge to main

Notes

• Every integration is bespoke. This skill is the map, not the destination.
• The depth of integration is the user's call. Genesis maps the terrain and presents options. The user decides how far to go.
• Don't gatekeep. If the user says "do it all," do it all. If they want just health monitoring, that's fine too.
• Be honest about complexity. "This will take multiple sessions" is useful information, not a reason to avoid starting.
• The goal is full co-pilot capability: anything the user could do with the program, Genesis should be able to do through the module interface.