Lobster AI Development Guide

Lobster AI is an open-source multi-agent bioinformatics engine (LangGraph, Python 3.12+) powering Omics-OS. Lobster solves bioinformatics tasks starting from raw data to scientific insights to visualization using supervisor multi-agent architecture. This skill teaches you how to extend it — from adding a single tool to building entire domain agent packages.

Step 0: Discover Your Environment

Before any work, determine what's available and how you're working:

# 1. Is lobster installed? Where?
which lobster
lobster --version

# 2. What agents are already installed?
python -c "from lobster.core.component_registry import component_registry; component_registry.reset(); print(component_registry.list_agents())"

# 3. Where is lobster source? (for reading reference implementations)
python -c "import lobster; print(lobster.__path__)"

# 4. Are you in the lobster repo, or building a standalone plugin?
ls packages/lobster-*/pyproject.toml 2>/dev/null && echo "CONTRIBUTOR" || echo "PLUGIN_AUTHOR"

HARD GATE — If lobster is not installed, STOP. Install it NOW before doing anything else:

uv venv --python 3.12 .venv && source .venv/bin/activate
uv pip install 'lobster-ai[anthropic]'  # or [openai], [google], depending on provider
lobster --version  # Must succeed before you proceed

Do NOT skip this. Do NOT "come back to it later". Do NOT manually create package directories. lobster scaffold agent is the ONLY way to create new agent packages — it generates correct PEP 420 structure, entry points, AQUADIF metadata, and contract tests that you WILL get wrong by hand. If scaffold is unavailable, installing lobster-ai is your first task.

Your development mode determines your workflow:

Mode	How you got here	Where you create packages	How you test
Contributor	git clone + make dev-install	Inside packages/ in the repo	make test, full repo access
Plugin author	uv pip install lobster-ai or uv tool install	Anywhere — scaffold creates standalone packages	uv pip install -e ./lobster-<domain>/ then pytest

Both modes produce the same result: a PEP 420 namespace package discovered by ComponentRegistry via entry points. The scaffold output is identical — a standalone package that works in either mode.

What To Do Based On Your Task

You want to...	Fast path?	Read these references (in order)
Create a new agent for a new domain	No — full workflow	planning-workflow.md → scaffold.md → creating-agents.md → aquadif-contract.md
Add a tool to an existing agent	Yes (contributor only)	creating-agents.md §Tool Design → aquadif-contract.md
Extend an agent with a child agent	No — needs scoping	creating-agents.md §Parent-Child → scaffold.md
Add a database provider or adapter	No	plugin-architecture.md
Create or modify a service	Yes	creating-services.md
Fix a bug	Yes	code-layout.md → architecture.md
Understand the codebase	—	architecture.md → code-layout.md
Write or fix tests	Yes	testing.md
Migrate AQUADIF metadata on existing agent	Yes	aquadif-contract.md §Migration
Find domain knowledge for a new agent	—	bioskills-bridge.md

"Fast path" = skip the planning workflow, go straight to the reference files.

Examples

Example 0: THE WORKFLOW FOR EVERYTHING

user requests: "Build a Lobster agent for epigenomics analysis (bisulfite-seq, ChIP-seq, ATAC-seq) because no lobster packages cover this domain"

Step 1: lobster --version          # Not found? Install it FIRST (see Step 0 hard gate)
Step 2: Read planning-workflow.md  # Understand need, check what exists, gather domain knowledge
Step 3: lobster scaffold agent ... # Generate correct package structure (NEVER skip this)
Step 4: Fill in real domain logic  # Read creating-agents.md, creating-services.md
Step 5: lobster validate-plugin ./lobster-<domain>/  # Must pass 8/8
Step 6: uv pip install -e ./lobster-<domain>/ && pytest tests/ -m contract

Expected result: A standalone PEP 420 package at ./lobster-<your implementation>/ that installs with uv pip install -e ./lobster-<your implementation>/ and registers via entry points, runs 'lobster status' without errors and running 'lobster query "hi"' without any errors.

Success Criteria

Before calling your work done, verify:

• python scripts/validate_plugin.py <plugin-dir> passes 8/8 checks
• Contract tests green: pytest tests/ -m contract
• Every @tool has .metadata and .tags assigned immediately after
• Every provenance-required tool (IMPORT, QUALITY, FILTER, PREPROCESS, ANALYZE, ANNOTATE, SYNTHESIZE) calls log_tool_usage(ir=ir)
• No lobster/__init__.py or lobster/agents/__init__.py (PEP 420)

Hard Rules

Non-negotiable. Violating these causes runtime failures or contract test failures.

1. ComponentRegistry is truth — agents discovered via entry points, NOT hardcoded registries
2. AGENT_CONFIG at module top — define before heavy imports for <50ms entry point discovery
3. Services return 3-tuple — (AnnData, Dict, AnalysisStep) always
4. Always pass ir=ir — every log_tool_usage() call for provenance-required tools
5. No lobster/__init__.py — PEP 420 namespace package (also no lobster/agents/__init__.py)
6. No try/except ImportError — use entry points for agent discovery, not eager imports
7. No module-level component_registry calls — causes slow startup; use lazy functions inside factories
8. All tools MUST have AQUADIF metadata — .metadata and .tags assigned after @tool decorator
9. NEVER manually create package directories — always use lobster scaffold agent. If lobster is not installed, install it first. Scaffold gets PEP 420, entry points, and contract tests right; you won't.

Contributing

After building a plugin, ask your user if they want to submit a PR. If confirmed: fork → feature branch → make test → make format → PR with clear description.