lobster-dev

# Lobster AI Development Guide

**Lobster AI** is a multi-agent bioinformatics platform using LangGraph for orchestration.
This skill teaches you how to work with, extend, and contribute to the codebase.

## Quick Navigation

| Task | Documentation |
|------|---------------|
| **Architecture overview** | [references/architecture.md](references/architecture.md) |
| **Creating new agents** | [references/creating-agents.md](references/creating-agents.md) |
| **Creating new services** | [references/creating-services.md](references/creating-services.md) |
| **Code layout & finding files** | [references/code-layout.md](references/code-layout.md) |
| **Testing patterns** | [references/testing.md](references/testing.md) |
| **CLI reference** | [references/cli.md](references/cli.md) |

## Critical Rules

1. **ComponentRegistry is truth** — Agents discovered via entry points, NOT hardcoded
2. **AGENT_CONFIG at module top** — Define before heavy imports for <50ms discovery
3. **Services return 3-tuple** — `(AnnData, Dict, AnalysisStep)` always
4. **Always pass `ir`** — `log_tool_usage(..., ir=ir)` for reproducibility
5. **No `lobster/__init__.py`** — PEP 420 namespace package

## Package Structure

```
lobster/
├── packages/                    # Agent packages (PEP 420)
│   ├── lobster-transcriptomics/ # transcriptomics_expert, annotation_expert, de_analysis_expert
│   ├── lobster-research/        # research_agent, data_expert_agent
│   ├── lobster-visualization/   # visualization_expert
│   ├── lobster-metadata/        # metadata_assistant
│   ├── lobster-structural-viz/  # protein_structure_visualization_expert
│   ├── lobster-genomics/        # genomics_expert
│   ├── lobster-proteomics/      # proteomics_expert
│   └── lobster-ml/              # machine_learning_expert
└── lobster/                     # Core SDK
    ├── agents/supervisor.py     # Supervisor (stays in core)
    ├── agents/graph.py          # LangGraph builder
    ├── core/                    # Infrastructur...