Contribution Workflow

SOIT changes should be small, scoped, and easy to verify. Public product behavior, architecture rules, and quality gates should stay aligned with the code.

Workflow

1. Start from the docs. Read the relevant capability or architecture page so the change lands where the platform expects it.
2. Identify the repository and subsystem being changed — backend layer placement matters; see Backend Boundaries.
3. Spec first. If the change adds or alters a capability contract, update the JSON Schema under app/kernel/specs/ with examples before writing runtime code.
4. Add targeted tests for the changed behavior — including the mandatory cases (scope isolation, spec rejection, trace emission) when they apply.
5. Run the relevant quality gate from Testing and Quality Gate locally.
6. Summarize verification in the pull request — what you ran, what passed, and any breaking-change impact.

PR checklist

Every backend PR must be able to answer yes to:

• Spec updated with examples (if a capability changed).
• Tenant/workspace scope enforced, with tests.
• run / run_step emitted for new execution paths.
• Kernel ports used for any external call.
• Breaking-change impact assessed.
• CI passes.

Contribution expectations

• Preserve tenant and workspace isolation — it is the platform's core security property.
• Keep API layers thin; business behavior lives in module services.
• Use kernel ports for external systems; never call provider SDKs from modules.
• Keep code comments, identifiers, and commit messages in English.
• Do not add local planning notes or private acceptance evidence to public product docs.
• Migrations are reviewed Alembic files, reversible when feasible.

Where to go next

• Backend Development — the engineering standard in detail.
• Development Setup — local environment.