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:

CODEBLOCK0

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	INLINECODE2 + INLINECODE3	Inside packages/ in the repo	INLINECODE5, 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"

CODEBLOCK2

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: INLINECODE14
• [ ] Every @tool has .metadata and .tags assigned immediately after
• [ ] Every provenance-required tool (IMPORT, QUALITY, FILTER, PREPROCESS, ANALYZE, ANNOTATE, SYNTHESIZE) calls INLINECODE18
• [ ] 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. 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.