Developer Quickstart

This guide is the fastest path from clone to confidence for contributors and evaluators working from the repo.

For repo context and first-read orientation, start at README.md.

• Python 3.10+
• pip/pip3
• Repository checked out locally

Install developer dependencies:

make install

Run this path first:

make install
make validate
make workflow-quickstart

Optional API/SDK smoke path:

python -m world_runtime serve --profile local
make sdk-example

Expected outcomes:

• make validate passes the schema + test baseline.
• make workflow-quickstart produces a reasoning summary and draft proposal.
• API/SDK smoke path returns a session and policy result.

Use this path when you are moving beyond the first smoke run:

1. Install dependencies: make install
2. Baseline confidence: make validate
3. Behavior and fixture checks as needed: make examples, make adapters, make evals
4. Compatibility checks when touching protocol/API surfaces: make protocol-compat, make public-api-compat
5. Full release gate before merge or release-critical changes: make m25-validate

For the complete command surface, see Makefile.

• Confirm Python version: python3 --version
• Retry install: make install
• If environment is stale, clear caches and reinstall:
  • make clean
  • make install

• Isolate schema failures: make schemas
• Isolate tests: make test-verbose
• Re-run baseline after fixes: make validate

• Re-run with clean baseline first: make validate
• Check adapter/domain-specific constraints with targeted runs (for example make air-traffic-evals)
• Re-run full evals after fixing scenario/adapter regressions: make evals

• Architecture: ARCHITECTURE.md
• Operator workflows: playbooks/operator-quickstart.md
• Observability diagnostics: playbooks/operator-observability-diagnostics.md
• Extension contracts: docs/EXTENSION_CONTRACTS.md
• Partner extension onboarding: docs/PARTNER_ONBOARDING.md
• Compatibility matrix: docs/COMPATIBILITY_MATRIX.md