AI Agent Onboarding Guide

This guide tells an AI coding or research agent what to read first in this workspace. The goal is to understand the current project boundary quickly before editing code or proposing architecture changes.

10-Minute Path

Read these first, in order:

/home/flare/sdlx/AGENTS.md
/home/flare/sdlx/docs/sdl-composer-loop-keeper.md
/home/flare/sdlx/composer/PRD.md
/home/flare/sdlx/ref-repos/README.md
/home/flare/sdlx/diagrams/sdl-overall-architecture.puml
/home/flare/sdlx/diagrams/labflow-labbridge-implemented.puml
/home/flare/sdlx/pace/diagrams/pace-implemented-architecture.puml
/home/flare/sdlx/labflow/AGENTS.md
/home/flare/sdlx/labbridge/AGENTS.md

This path should establish the main boundaries:

Scientist Agent = scientific goals, hypotheses, next candidates
Composer = nanobot-based process-composition tools that turn requirements into PACE package drafts
PACE / Loop Keeper = loop execution, result recording, completeness checks
labflow = workflow/module development, validation, test, run, and export platform
composer workflow pool = uploaded labflow YAML modules used by Composer
labbridge = device capability boundary, policy, state, operations, audit, artifacts

Important Composer boundary:

nanobot owns the generic agent runtime, sessions, provider routing, tool loop,
OpenAI-compatible API, and WebUI/channel.

Composer owns SDL domain tools, process skill packages, workflow pool indexing,
LabBridge capability snapshots, deterministic PACE package building, validation
reports, and human-review job state.

Workspace Overview

Read:

/home/flare/sdlx/README.md
/home/flare/sdlx/AGENTS.md
/home/flare/sdlx/docs/lab-architecture.md
/home/flare/sdlx/docs/sdl-composer-loop-keeper.md

Use these diagrams:

/home/flare/sdlx/diagrams/sdl-overall-architecture.puml
/home/flare/sdlx/diagrams/lab-architecture-detailed-roadmap.puml

Use sdl-overall-architecture.puml as the first architecture picture. Use lab-architecture-detailed-roadmap.puml only when you need the longer-term lab roadmap, including communication planes, robotics, and feedback data stores.

Current Implementation Overview

Read this diagram before jumping into code:

/home/flare/sdlx/diagrams/labflow-labbridge-implemented.puml
/home/flare/sdlx/pace/diagrams/pace-implemented-architecture.puml

It maps the current source code:

PACE FastAPI routes, loop runner, package loader, archive store, result_contract extraction
labflow FastAPI routes
labflow runner and SQLite store
labflow MCP JSON-RPC gateway client
labbridge FastMCP tools
labbridge Admin HTTP API
labbridge registry, operations, controller protocol, artifact service, traces
MQTT simple device path
controller-backed operation path

Use this compact diagram for human-facing discussion:

/home/flare/sdlx/diagrams/labflow-labbridge-quick-view.puml

PACE-specific diagrams:

/home/flare/sdlx/pace/diagrams/pace-implemented-architecture.puml
/home/flare/sdlx/pace/diagrams/loop-run-lifecycle.puml
/home/flare/sdlx/pace/diagrams/result-contract-evidence-flow.puml

labflow Reading Path

Read:

/home/flare/sdlx/labflow/AGENTS.md
/home/flare/sdlx/labflow/README.md
/home/flare/sdlx/labflow/PRD.md

Then read diagrams:

/home/flare/sdlx/labflow/diagrams/workflow-authoring-flow.puml
/home/flare/sdlx/labflow/diagrams/run-state-machine.puml
/home/flare/sdlx/labflow/diagrams/step-execution-sequence.puml

Important boundary:

labflow is not Loop Keeper.
labflow is not Composer; developed labflow YAML can be uploaded to Composer's pool.
labflow does not own the experiment database.
labflow does not decide the next scientific hypothesis.
labflow does not talk directly to MQTT, GPIO, serial devices, robot SDKs, or camera SDKs.

Implementation anchors:

/home/flare/sdlx/labflow/backend/src/labflow/api.py
/home/flare/sdlx/labflow/backend/src/labflow/api_workflows.py
/home/flare/sdlx/labflow/backend/src/labflow/api_runs.py
/home/flare/sdlx/labflow/backend/src/labflow/api_resources.py
/home/flare/sdlx/labflow/backend/src/labflow/schema.py
/home/flare/sdlx/labflow/backend/src/labflow/preflight.py
/home/flare/sdlx/labflow/backend/src/labflow/runner.py
/home/flare/sdlx/labflow/backend/src/labflow/runner_lifecycle.py
/home/flare/sdlx/labflow/backend/src/labflow/runner_steps.py
/home/flare/sdlx/labflow/backend/src/labflow/runner_io.py
/home/flare/sdlx/labflow/backend/src/labflow/gateway_client.py
/home/flare/sdlx/labflow/backend/src/labflow/store_schema.py

labbridge Reading Path

Read:

/home/flare/sdlx/labbridge/AGENTS.md
/home/flare/sdlx/labbridge/README.md
/home/flare/sdlx/labbridge/docs/mcp-tools.md
/home/flare/sdlx/labbridge/docs/controller-protocol.md
/home/flare/sdlx/labbridge/docs/registry.md
/home/flare/sdlx/labbridge/docs/artifact-storage.md

Then read diagrams:

/home/flare/sdlx/labbridge/diagrams/esphome-mqtt-runtime.puml
/home/flare/sdlx/labbridge/diagrams/controller-operation-flow.puml
/home/flare/sdlx/labbridge/diagrams/workflow-gateway-trace.puml
/home/flare/sdlx/labbridge/diagrams/device-integration-decision.puml

Important boundary:

labbridge is the only device capability boundary.
All writes go through call_capability.
Gateway stores metadata, operation state, artifact metadata, and audit.
Device SDKs, vision logic, navigation, arm motion, and instrument private protocols stay in controllers or algorithm services.

Implementation anchors:

/home/flare/sdlx/labbridge/src/labbridge/main.py
/home/flare/sdlx/labbridge/src/labbridge/service.py
/home/flare/sdlx/labbridge/src/labbridge/mcp/fastmcp.py
/home/flare/sdlx/labbridge/src/labbridge/mcp/views.py
/home/flare/sdlx/labbridge/src/labbridge/capability_calls/service.py
/home/flare/sdlx/labbridge/src/labbridge/operations/service.py
/home/flare/sdlx/labbridge/src/labbridge/controllers/service.py
/home/flare/sdlx/labbridge/src/labbridge/integrations/manifest_sync.py
/home/flare/sdlx/labbridge/src/labbridge/admin/server.py
/home/flare/sdlx/labbridge/src/labbridge/artifacts/service.py
/home/flare/sdlx/labbridge/src/labbridge/traces/service.py
/home/flare/sdlx/labbridge/src/labbridge/_registry/schema.py

Task-Based Reading

For workflow editor or runner changes:

labflow/AGENTS.md
labflow/README.md
labflow/PRD.md
labflow/diagrams/workflow-authoring-flow.puml
labflow/diagrams/run-state-machine.puml
labflow/backend/src/labflow/schema.py
labflow/backend/src/labflow/runner*.py

For gateway MCP tool changes:

labbridge/AGENTS.md
labbridge/docs/mcp-tools.md
labbridge/src/labbridge/mcp/fastmcp.py
labbridge/src/labbridge/mcp/views.py
labbridge/src/labbridge/capability_calls/service.py

For controller-backed devices:

labbridge/docs/controller-protocol.md
labbridge/docs/controller-patterns.md
labbridge/diagrams/controller-operation-flow.puml
labbridge/examples/camera0_controller/README.md
labbridge/examples/vision_agent0_controller/README.md
labbridge/examples/amr0_controller/README.md

For artifacts and traces:

labbridge/docs/artifact-storage.md
labbridge/diagrams/workflow-gateway-trace.puml
labbridge/src/labbridge/artifacts/service.py
labbridge/src/labbridge/traces/service.py

For PACE / Loop Keeper work:

docs/sdl-composer-loop-keeper.md
docs/next-step-golden-loop.md
diagrams/sdl-overall-architecture.puml
diagrams/lab-architecture-detailed-roadmap.puml
pace/README.md
pace/PRD.md
pace/diagrams/pace-implemented-architecture.puml
labflow/README.md
labflow/PRD.md

Rules Before Editing

Before changing code:

Read the nearest AGENTS.md.
Read the current implementation diagram if touching both projects.
Search code with rg before editing.
Do not rename labbridge.
Do not edit .env, secrets, data, logs, run, or generated runtime artifacts.
Do not move hardware SDK or algorithm logic into labbridge.
Do not make labflow responsible for Loop Keeper or Experiment DB duties.

After changing backend code:

Run the project-specific tests or compile checks when feasible.
Update docs and diagrams when public API, MCP tools, workflow assumptions, registry schema, or controller protocol changes.