{"skill":{"slug":"lobster-bio-dev","displayName":"LobsterBio - Dev","summary":"Develop, extend, and contribute to Lobster AI — the multi-agent bioinformatics engine.\nUse when working on Lobster codebase, creating agents/services, understanding architecture,\nfixing bugs, adding features, or contributing to the open-source project.\n\nTrigger phrases: \"add agent\", \"create service\", \"extend lobster\", \"contribute\",\n\"understand architecture\", \"how does X work in lobster\", \"fix bug\", \"add feature\",\n\"write tests\", \"lobster development\", \"agent development\", \"bioinformatics code\"","description":"---\nname: lobster-dev\ndescription: |\n  Develop, extend, and contribute to Lobster AI — the multi-agent bioinformatics engine.\n  Use when working on Lobster codebase, creating agents/services, understanding architecture,\n  fixing bugs, adding features, or contributing to the open-source project.\n  \n  Trigger phrases: \"add agent\", \"create service\", \"extend lobster\", \"contribute\",\n  \"understand architecture\", \"how does X work in lobster\", \"fix bug\", \"add feature\",\n  \"write tests\", \"lobster development\", \"agent development\", \"bioinformatics code\"\n---\n\n# Lobster AI Development Guide\n\n**Lobster AI** is a multi-agent bioinformatics platform using LangGraph for orchestration.\nThis skill teaches you how to work with, extend, and contribute to the codebase.\n\n## Quick Navigation\n\n| Task | Documentation |\n|------|---------------|\n| **Architecture overview** | [references/architecture.md](references/architecture.md) |\n| **Creating new agents** | [references/creating-agents.md](references/creating-agents.md) |\n| **Creating new services** | [references/creating-services.md](references/creating-services.md) |\n| **Code layout & finding files** | [references/code-layout.md](references/code-layout.md) |\n| **Testing patterns** | [references/testing.md](references/testing.md) |\n| **CLI reference** | [references/cli.md](references/cli.md) |\n\n## Critical Rules\n\n1. **ComponentRegistry is truth** — Agents discovered via entry points, NOT hardcoded\n2. **AGENT_CONFIG at module top** — Define before heavy imports for <50ms discovery\n3. **Services return 3-tuple** — `(AnnData, Dict, AnalysisStep)` always\n4. **Always pass `ir`** — `log_tool_usage(..., ir=ir)` for reproducibility\n5. **No `lobster/__init__.py`** — PEP 420 namespace package\n\n## Package Structure\n\n```\nlobster/\n├── packages/                    # Agent packages (PEP 420)\n│   ├── lobster-transcriptomics/ # transcriptomics_expert, annotation_expert, de_analysis_expert\n│   ├── lobster-research/        # research_agent, data_expert_agent\n│   ├── lobster-visualization/   # visualization_expert\n│   ├── lobster-metadata/        # metadata_assistant\n│   ├── lobster-structural-viz/  # protein_structure_visualization_expert\n│   ├── lobster-genomics/        # genomics_expert\n│   ├── lobster-proteomics/      # proteomics_expert\n│   └── lobster-ml/              # machine_learning_expert\n└── lobster/                     # Core SDK\n    ├── agents/supervisor.py     # Supervisor (stays in core)\n    ├── agents/graph.py          # LangGraph builder\n    ├── core/                    # Infrastructure (registry, data_manager, provenance)\n    ├── services/                # Analysis services\n    └── tools/                   # Agent tools\n```\n\n## Quick Commands\n\n```bash\n# Setup (development)\nmake dev-install              # Full dev setup with editable install\nmake test                     # Run all tests\nmake format                   # black + isort\n\n# Setup (end-user testing via uv tool)\nuv tool install 'lobster-ai[full,anthropic]'   # Install as users see it\nuv tool upgrade lobster-ai                      # Upgrade to latest\n\n# Running\nlobster chat                  # Interactive mode\nlobster query \"your request\"  # Single-turn\n\n# Testing\npytest tests/unit/            # Fast unit tests\npytest tests/integration/     # Integration tests\n```\n\n## Service Pattern (Essential)\n\nAll services return a 3-tuple:\n\n```python\ndef analyze(self, adata, **params) -> Tuple[AnnData, Dict, AnalysisStep]:\n    # Your analysis logic\n    stats = {\"n_cells\": adata.n_obs, \"status\": \"complete\"}\n    ir = AnalysisStep(\n        activity_type=\"analyze\",\n        inputs={\"n_obs\": adata.n_obs},\n        outputs=stats,\n        params=params\n    )\n    return processed_adata, stats, ir\n```\n\nTools wrap services:\n\n```python\n@tool\ndef analyze_modality(modality_name: str, **params) -> str:\n    result, stats, ir = service.analyze(adata, **params)\n    data_manager.log_tool_usage(\"analyze\", params, stats, ir=ir)  # IR mandatory!\n    return f\"Complete: {stats}\"\n```\n\n## Agent Registration (Entry Points)\n\nAgents register via `pyproject.toml`:\n\n```toml\n[project.entry-points.\"lobster.agents\"]\nmy_agent = \"lobster.agents.my_domain.my_agent:AGENT_CONFIG\"\n```\n\nAGENT_CONFIG must be defined at module top (before imports):\n\n```python\n# lobster/agents/mydomain/my_agent.py\nfrom lobster.config.agent_registry import AgentRegistryConfig\n\nAGENT_CONFIG = AgentRegistryConfig(\n    name=\"my_agent\",\n    display_name=\"My Expert Agent\",\n    description=\"What this agent does\",\n    factory_function=\"lobster.agents.mydomain.my_agent.my_agent\",\n    handoff_tool_name=\"handoff_to_my_agent\",\n    handoff_tool_description=\"Assign tasks for my domain analysis\",\n    tier_requirement=\"free\",  # All official agents are free\n)\n\n# Heavy imports AFTER config\nfrom lobster.core.data_manager_v2 import DataManagerV2\n# ... rest of implementation\n```\n\n## Key Files\n\n| File | Purpose |\n|------|---------|\n| `lobster/agents/graph.py` | LangGraph orchestration |\n| `lobster/core/component_registry.py` | Agent discovery |\n| `lobster/core/data_manager_v2.py` | Data/workspace management |\n| `lobster/core/provenance.py` | W3C-PROV tracking |\n| `lobster/cli.py` | CLI implementation |\n\n## Online Documentation\n\nFull documentation at **docs.omics-os.com** (or local `docs-site/`):\n\n- **Getting Started**: `docs/getting-started/`\n- **Core SDK**: `docs/core/`\n- **Agents**: `docs/agents/`\n- **Developer Guide**: `docs/developer/`\n- **API Reference**: `docs/api-reference/`\n\n## Common Tasks\n\n### Adding a New Agent\n\n1. Create package: `packages/lobster-mydomain/`\n2. Define AGENT_CONFIG at top of agent file\n3. Register entry point in `pyproject.toml`\n4. Implement agent with tools\n5. Add tests in `tests/unit/agents/`\n\nSee [references/creating-agents.md](references/creating-agents.md) for full guide.\n\n### Adding a New Service\n\n1. Create service class in appropriate package\n2. Implement 3-tuple return pattern\n3. Wrap in tool with `log_tool_usage`\n4. Add unit tests\n\nSee [references/creating-services.md](references/creating-services.md) for full guide.\n\n### Understanding Data Flow\n\n```\nUser Query → CLI → LobsterClientAdapter → AgentClient\n                                              ↓\n                            LangGraph (supervisor → agents)\n                                              ↓\n                               Services → DataManagerV2\n                                              ↓\n                                    Results + Provenance\n```\n\n## Testing\n\n```bash\n# Unit tests (fast, no external deps)\npytest tests/unit/ -v\n\n# Integration tests (may need env vars)\npytest tests/integration/ -v\n\n# Specific test\npytest tests/unit/test_my_feature.py -v\n\n# With coverage\npytest --cov=lobster tests/\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create feature branch: `git checkout -b feature/my-feature`\n3. Make changes following patterns above\n4. Run tests: `make test`\n5. Format code: `make format`\n6. Submit PR with clear description\n","tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":1380,"installsAllTime":52,"installsCurrent":1,"stars":0,"versions":2},"createdAt":1770860265364,"updatedAt":1778487906275},"latestVersion":{"version":"1.0.1","createdAt":1770985966234,"changelog":"- Added developer instructions for installing and upgrading via the `uv` tool, reflecting typical end-user workflows.\n- Clarified that all official agents have a `tier_requirement` of \"free\" in `AGENT_CONFIG`.\n- Updated Quick Commands and setup steps to distinguish between development and end-user installation procedures.\n- Minor improvements to formatting and developer guidance in SKILL.md and referenced documentation files.","license":null},"metadata":null,"owner":{"handle":"cewinharhar","userId":"s172ezy20zdeb416qcyvxnaced8845q6","displayName":"cewinharhar","image":"https://avatars.githubusercontent.com/u/64527798?v=4"},"moderation":null}