Scaffold Generator
Generate complete agent packages from the CLI with lobster scaffold agent
Scaffold Generator
The lobster scaffold agent command generates a complete, installable agent package from a single command. The output passes all 8 validation checks immediately and includes contract tests that run out of the box.
Prefer the manual approach? See Creating Agent Packages for the step-by-step guide without scaffolding.
Quick Start
lobster scaffold agent \
--name epigenomics_expert \
--display-name "Epigenomics Expert" \
--description "ChIP-seq and ATAC-seq analysis for histone modifications and chromatin accessibility"This creates a lobster-epigenomics/ directory with a working agent package. To add sub-agents:
lobster scaffold agent \
--name epigenomics_expert \
--display-name "Epigenomics Expert" \
--description "Epigenomics analysis" \
--children methylation_expert,chromatin_expertAfter generation, validate the output:
What Gets Generated
lobster-epigenomics/
├── pyproject.toml # Entry points, dependencies, namespace config
├── README.md # Installation and usage
├── lobster/ # PEP 420 namespace (NO __init__.py)
│ └── agents/ # PEP 420 namespace (NO __init__.py)
│ └── epigenomics/
│ ├── __init__.py # Minimal: exports state class only
│ ├── epigenomics_expert.py # AGENT_CONFIG + factory function
│ ├── shared_tools.py # 4 example tools with AQUADIF metadata
│ ├── state.py # LangGraph AgentState subclass
│ ├── config.py # Platform configuration dataclass
│ └── prompts.py # System prompt factory with XML sections
└── tests/
├── conftest.py # mock_data_manager + workspace_path fixtures
└── test_contract.py # AgentContractTestMixin (passes immediately)PEP 420 critical: There must be no __init__.py at the lobster/ or lobster/agents/ level. Only the domain directory has one. The validator checks this.
For a detailed explanation of why this layout matters, see Package Structure.
Key Generated Files
| File | What It Contains |
|---|---|
epigenomics_expert.py | AGENT_CONFIG (before heavy imports) + factory function with standard signature |
shared_tools.py | 4 placeholder tools (IMPORT, QUALITY, ANALYZE, UTILITY) with AQUADIF .metadata and .tags |
state.py | AgentState subclass with next: str field |
config.py | PlatformConfig dataclass + PLATFORM_CONFIGS dict + detection helpers |
prompts.py | create_epigenomics_expert_prompt() with XML sections (Identity, Environment, Responsibilities, Tools, Rules) |
test_contract.py | AgentContractTestMixin class — 14 contract checks that pass immediately |
CLI Reference
lobster scaffold agent
| Flag | Required | Default | Description |
|---|---|---|---|
--name | Yes | — | Agent name in snake_case (e.g., epigenomics_expert) |
--display-name | Yes | — | Human-readable name (e.g., "Epigenomics Expert") |
--description | Yes | — | Agent capabilities description |
--children | No | — | Comma-separated child agent names |
--output-dir, -o | No | . | Output directory |
--author-name | No | Lobster AI Community | Package author name |
--author-email | No | community@lobsterbio.com | Author email |
The --name flag drives all derived names: epigenomics_expert produces package lobster-epigenomics, domain directory epigenomics/, and class name EpigenomicsExpert.
lobster validate-plugin
Validates a scaffolded (or manually created) agent package against 8 structural checks:
| Check | What It Validates |
|---|---|
| PEP 420 compliance | No __init__.py at namespace boundaries (lobster/, lobster/agents/) |
| Entry points | pyproject.toml has [project.entry-points."lobster.agents"] with :AGENT_CONFIG format |
| AGENT_CONFIG position | AGENT_CONFIG defined before any langgraph/langchain imports (AST check) |
| Factory signature | Parameters include data_manager, callback_handler, agent_name, delegation_tools, workspace_path |
| AQUADIF metadata | Every @tool function has .metadata with categories and provenance |
| Provenance calls | Tools with "provenance": True call log_tool_usage(ir=ir) |
| Import boundaries | No from lobster.agents.<other_domain> imports (package isolation) |
| No ImportError guard | Domain __init__.py has no try/except ImportError pattern |
Exit code 0 if all checks pass, 1 if any fail.
Next Steps After Scaffolding
Enhance tools in shared_tools.py
Replace the 4 placeholder tools with real domain-specific logic. Each tool must follow the AQUADIF taxonomy — assign .metadata with the correct category and set provenance: true for data-transforming operations.
Configure platforms in config.py
Add platform-specific configurations as dataclasses. For example, an epigenomics agent might define configs for ChIP-seq, ATAC-seq, and bisulfite sequencing platforms with default parameters for each.
Refine the system prompt in prompts.py
Edit the XML sections to accurately describe your agent's capabilities, available tools, and behavioral rules. The generated prompt has the correct structure — fill in the domain-specific content.
Install the package locally
cd lobster-epigenomics/
uv pip install -e ".[dev]"For contributors working inside the lobster repo, scaffold with -o packages/ and run make dev-install instead.
Validate and test
# Structural validation (8 checks)
lobster validate-plugin ./lobster-epigenomics/
# Contract tests (should pass immediately, even before adding real tools)
pytest tests/ -m contract -vVerify discovery
python -c "
from lobster.core.component_registry import component_registry
component_registry.reset()
print(component_registry.has_agent('epigenomics_expert'))
"This should print True. If it prints False, check that the package is installed (uv pip list | grep lobster-epigenomics) and that entry points are declared in pyproject.toml.
Multi-Agent Packages
Use --children to scaffold a parent agent with sub-agents:
lobster scaffold agent \
--name epigenomics_expert \
--display-name "Epigenomics Expert" \
--description "Epigenomics analysis" \
--children methylation_expert,chromatin_expertThis generates additional files for each child (methylation_expert.py, chromatin_expert.py) and wires their entry points in pyproject.toml:
[project.entry-points."lobster.agents"]
epigenomics_expert = "lobster.agents.epigenomics.epigenomics_expert:AGENT_CONFIG"
methylation_expert = "lobster.agents.epigenomics.methylation_expert:AGENT_CONFIG"
chromatin_expert = "lobster.agents.epigenomics.chromatin_expert:AGENT_CONFIG"The parent's AGENT_CONFIG automatically includes child_agents=["methylation_expert", "chromatin_expert"] and supervisor_accessible=True, while children have supervisor_accessible=False. Delegation tools between parent and children are wired at graph creation time by the Lobster runtime.