Skip to main content

Developer onboarding

Choose the owning repository​

Use repository boundaries to decide where a change belongs. Protocol changes belong in contracts; endpoint runtime/collection belongs in agent; backend processing and control belong in backend; documentation is independent. Avoid changes in a sibling just to make a local checkout compile.

Clone only the repositories you need, using the project's GitHub remotes. Private access uses your existing authenticated Git setup. Backend and agent import published contracts rather than a relative filesystem path. The module file is authoritative for the toolchain and version.

First working loop​

RepositoryInitial gateAdditional evidence
Backendmake verify, make buildmake test-integration, make test-load, make vulncheck where relevant
Agentmake verifymake vulncheck; compatibility/failure tests for changed behavior
Contractsmake verify, make breakingConsumer compatibility against released bindings
V2 frontendNo build yetEstablish implementation and CI before claiming support

Read before changing behavior​

Inspect the owning package, tests, accepted ADRs, contracts, configuration, and composition root. For data-plane work, identify the durable side effect and commit point. For control-plane work, identify authentication, permission, tenant scope, and audit trail. For stateful work, identify partition ownership and recovery.

Do not create a generic helper or new process before searching for an existing owner. Backend architecture tests enforce dependency direction, and agent tests inspect transitive boundaries across build tags.

Debug at the boundary​

Use structured logs and relevant metrics, then reproduce with the smallest meaningful test. A broker outage, refusal, store error, and state activation rejection are different failure classes. Avoid weakening TLS or changing offset commits to make a local test pass.

Read implementation workflows, testing, and contribution expectations for the next step.

Source evidence​

Reviewed against the source baseline. Seagull-backend-v2/Makefile · Seagull-agent-v2/Makefile · Seagull-contracts/Makefile · Seagull-backend-v2/tests/architecture/dependencies_test.go.