HeLa MCP Ecosystem: Workflows & Integration Guide

This document defines the standard operational workflows and cross-MCP coordination patterns enabled by the HeLa MCP Ecosystem.

1. Architectural Foundation: Dual-Backbone Coordination

Every profile in the HeLa MCP Ecosystem is anchored by two coordinating backbone servers:

flowchart TB
    Agent["Agent / LLM Orchestrator"]

    Mitosis["HeLa Mitosis<br/>(Orchestrator)<br/>- Dynamic Routing<br/>- Step Reasoning<br/>- Tool Planning"]
    Genome["HeLa Genome<br/>(State & Memory)<br/>- Knowledge Graph<br/>- Entities / Relations<br/>- Observations"]

    Membrane["HeLa Membrane<br/>Workspace FS"]
    Nucleus["HeLa Nucleus<br/>Command Exec"]
    Ribosome["HeLa Ribosome<br/>PTY Harness"]
    Enzyme["HeLa Enzyme<br/>Research / Wiki"]
    Cytosol["HeLa Cytosol<br/>Browser DOM"]

    Agent --> Mitosis & Genome
    Mitosis <-->|"Shared Context"| Genome
    Mitosis & Genome --> Membrane & Nucleus & Ribosome & Enzyme & Cytosol

• HeLa Mitosis (hela-mitosis): Acts as the cognitive orchestrator. It decomposes complex prompts, analyzes tool performance, and runs Needle-backed sequentialthinking step-by-step logic (each thought is an observe → decide → execute agent step recorded in AgentState).
• HeLa Genome (hela-genome): Acts as the immutable project memory. It stores entities, relations, observations, and session milestones in memory.db.

2. Canonical Workflows Catalog

Workflow A: Autonomous Feature Engineering

Primary Profiles: dev-workspace, headless-server Components: hela-genome → hela-mitosis → hela-membrane → hela-nucleus → hela-genome

sequenceDiagram
    participant Agent
    participant Genome as HeLa Genome
    participant Mitosis as HeLa Mitosis
    participant Membrane as HeLa Membrane
    participant Nucleus as HeLa Nucleus

    Agent->>Genome: get_session_context / search_nodes(task)
    Genome-->>Agent: Previous architecture & constraints
    Agent->>Mitosis: analyze_with_sequential_thinking(feature_req)
    Mitosis-->>Agent: Step-by-step implementation plan
    Agent->>Membrane: read_file / write_file(source_code)
    Membrane-->>Agent: Code written to workspace
    Agent->>Nucleus: execute_command("npm test" / "pytest")
    Nucleus-->>Agent: Test run output
    Agent->>Genome: memory_edit(action="add_observations", observations=[…])

Step-by-Step Tool Sequence:

1. Context Restoration: Call get_session_context on hela-genome to retrieve active architectural decisions and dependencies.
2. Decomposition: Call llm_decompose_task or sequentialthinking on hela-mitosis to generate an execution plan.
3. Workspace Modification: Call read_file and write_file on hela-membrane to apply minimal, production-ready code changes.
4. Validation: Call execute_command on hela-nucleus (or rtk wrapper) to run automated unit tests.
5. State Recording: Call memory_edit on hela-genome to commit progress to the knowledge graph.

Workflow B: Deep Research & Architecture Synthesis

Primary Profiles: research, dev-workspace Components: hela-enzyme → hela-cytosol → hela-mitosis → hela-genome → hela-membrane

sequenceDiagram
    participant Agent
    participant Enzyme as HeLa Enzyme
    participant Cytosol as HeLa Cytosol
    participant Mitosis as HeLa Mitosis
    participant Genome as HeLa Genome
    participant Membrane as HeLa Membrane

    Agent->>Enzyme: wikipedia_search / google_search(query)
    Enzyme-->>Agent: Structured technical summaries & citations
    Agent->>Cytosol: browser_navigate(spec_url) -> browser_get_content(format=markdown)
    Cytosol-->>Agent: Live technical documentation content
    Agent->>Mitosis: llm_summarize(extracted_data)
    Mitosis-->>Agent: Synthesized architectural comparison
    Agent->>Genome: memory_edit(action="create_entities") + memory_edit(action="add_observations")
    Agent->>Membrane: write_file("docs/architecture/spec-x.md")

Step-by-Step Tool Sequence:

1. Knowledge Retrieval: Query wikipedia_search or google_search via hela-enzyme for background literature and reference APIs.
2. Live Web Extraction: Use browser_navigate and browser_get_content(format=markdown) via hela-cytosol to extract documentation from official docs sites.
3. Synthesis: Run llm_summarize and analyze_with_sequential_thinking on hela-mitosis to synthesize key architectural trade-offs.
4. Knowledge Ingestion: Call memory_edit on hela-genome linking findings to existing system components.
5. Artifact Generation: Save the final report using write_file on hela-membrane.

Workflow C: End-to-End Web Feature with Design & Browser Verification

Primary Profiles: web-devops, dev-workspace Components: hela-phenotype → hela-membrane → hela-nucleus → hela-cytosol → hela-genome

sequenceDiagram
    participant Agent
    participant Phenotype as HeLa Phenotype
    participant Membrane as HeLa Membrane
    participant Nucleus as HeLa Nucleus
    participant Cytosol as HeLa Cytosol
    participant Genome as HeLa Genome

    Agent->>Phenotype: design_tokens(action="theme") / design_tokens(action="tailwind")
    Phenotype-->>Agent: Design tokens & OKLCH color palette
    Agent->>Membrane: write_file("tailwind.config.js" & component files)
    Agent->>Nucleus: execute_command("npm run dev")
    Nucleus-->>Agent: Local dev server active on port 3000
    Agent->>Cytosol: browser_navigate("http://localhost:3000") -> browser_screenshot
    Cytosol-->>Agent: Rendered visual screenshot & accessibility tree
    Agent->>Genome: memory_edit(action="add_observations", observations=["Design verified on DOM & visual snapshot"])

Step-by-Step Tool Sequence:

1. Design System Token Generation: Call design_tokens, palette, or logo_workflow on hela-phenotype.
2. Component Implementation: Write JSX/Tailwind files using write_file on hela-membrane.
3. Dev Server Launch: Launch background local web server using execute_command on hela-nucleus.
4. Visual & Accessibility Verification: Navigate to http://localhost:3000 via browser_navigate on hela-cytosol, verify DOM via browser_get_content(format=axtree), and take visual snapshot with browser_screenshot.
5. Milestone Recording: Save verification screenshot path and milestone to hela-genome.

Live Production References Generated by HeLa Phenotype (the-designer):

• Ellis UI Archive / The Collection — 24 bespoke anti-slop design systems (Game Boy 8-bit, Top Secret Dossier, Nutrition Facts, Library Card, Gothic Tome, Swiss Archival).

Workflow D: Mobile App Test Automation & Verification

Primary Profiles: android-testing, all Components: hela-genome → hela-nucleus → hela-receptor → hela-genome

sequenceDiagram
    participant Agent
    participant Genome as HeLa Genome
    participant Nucleus as HeLa Nucleus
    participant Receptor as HeLa Receptor

    Agent->>Genome: get_session_context (device test suite)
    Agent->>Nucleus: execute_command("adb devices")
    Nucleus-->>Agent: Connected device ID detected
    Agent->>Receptor: start_session(deviceId) -> ui_dump
    Receptor-->>Agent: XML/axtree hierarchy of active mobile screen
    Agent->>Receptor: tap(element_id) / input_text("user_input")
    Receptor-->>Agent: UI transition complete
    Agent->>Receptor: screenshot("artifacts/test-pass.png")
    Agent->>Genome: memory_edit(action="add_observations", observations=["Mobile flow X verified on physical Android"])

Step-by-Step Tool Sequence:

1. Device Discovery: Call device_list on hela-receptor or execute_command("adb devices") on hela-nucleus.
2. Session Initialization: Call start_session on hela-receptor.
3. UI Hierarchy Inspection: Call ui_dump or ui_find_element to inspect Android view hierarchy token-efficiently via XML rather than screenshots.
4. Interaction: Execute tap, input_text, scroll, or key_event to execute test scenario.
5. Visual Proof & Persistence: Call screenshot and record test result observation in hela-genome.

Workflow E: Autonomous 3D Asset Creation & Render Pipeline

Primary Profiles: 3d-modeling, all Components: hela-genome → hela-mitosis → hela-plastid → hela-membrane → hela-genome

sequenceDiagram
    participant Agent
    participant Genome as HeLa Genome
    participant Mitosis as HeLa Mitosis
    participant Plastid as HeLa Plastid
    participant Membrane as HeLa Membrane

    Agent->>Genome: search_nodes("3D Assets")
    Agent->>Mitosis: generate_route_suggestions("Procedural chair generation")
    Agent->>Plastid: generate_modeling_plan("Modern lounge chair")
    Plastid-->>Agent: Phased Python Blender script
    Agent->>Plastid: execute_blender_code(script) -> render_output
    Plastid-->>Agent: High-resolution render output PNG
    Agent->>Plastid: save_blend("assets/chair.blend")
    Agent->>Genome: memory_edit(action="add_observations", observations=["Generated 3D chair asset and render"])

Step-by-Step Tool Sequence:

1. Asset Requirement Analysis: Retrieve scene requirements from hela-genome.
2. Plan Synthesis: Call generate_modeling_plan on hela-plastid.
3. Procedural Execution: Run execute_blender_code to generate geometry, apply materials, and setup lights.
4. Render Output: Trigger render_output and get_fast_feedback for visual QA.
5. Persistence: Save .blend file via save_blend and register the asset entity in hela-genome.

Workflow F: Long-Horizon Complex Refactor with PTY Harness

Primary Profiles: dev-workspace, headless-server Components: hela-ribosome → hela-nucleus → hela-genome

sequenceDiagram
    participant Agent
    participant Ribosome as HeLa Ribosome
    participant Nucleus as HeLa Nucleus
    participant Genome as HeLa Genome

    Agent->>Ribosome: session_spawn("long-build", "mvn clean install -T 4")
    Ribosome-->>Agent: Session spawned (ID: sess-101)
    Agent->>Ribosome: session_read("sess-101") (bounded polling)
    Ribosome-->>Agent: Streamed stdout/stderr chunk
    Agent->>Nucleus: execute_command("git status")
    Agent->>Genome: memory_edit(action="add_observations", observations=["Long refactor build verified via PTY session"])
    Agent->>Ribosome: session_close("sess-101")

Step-by-Step Tool Sequence:

1. Interactive Session Creation: Call session_spawn on hela-ribosome for interactive, long-running processes (compilers, debuggers, REPLs).
2. Session Monitoring: Read process output with session_read or send input with session_write.
3. Session Termination: Clean up process with session_close.
4. Memory Recording: Log completed refactor state to hela-genome.

3. Best Practices & Token Economy

1. Structured Memory Over Raw History: Always record key findings and milestones to hela-genome so subsequent agent turns do not need to re-read thousands of lines of raw logs.
2. Hierarchy Inspection Over Full Screenshots: For web (hela-cytosol) and mobile (hela-receptor), prefer accessibility trees and XML dumps for element location, reserving bitmap screenshots for final visual verification.
3. Fail-Fast Pre-Validation: Always verify prerequisite binary availability via ./setup.sh doctor before launching complex cross-MCP pipelines.