CommonGround: Instructions file for Codex

Repository Guidelines

Repository Role

CommonGround/ is the active implementation repository for CommonGround.

Primary implementation paths:

• CommonGround/: kernel, truth, service, SDK, and CLI code.
• Integrations/nanobot/: external runtime, provision, and leaf worker integration.
• tests/: regression coverage and executable contracts.
• docs/: current architecture and design documentation.

Documentation Priority

When working in this repository, read these documents first:

1. docs/en/01-constitution.md or docs/zh/01-constitution.md
2. docs/en/02-three-plane-model.md or docs/zh/02-three-plane-model.md
3. docs/en/03-design-review-principles.md or docs/zh/03-design-review-principles.md
4. docs/en/introduction/ or docs/zh/introduction/

The English and Chinese documentation trees are parallel current surfaces. Background material can explain design history, but it does not override the current docs or code.

Code Structure

Important paths:

• CommonGround/contracts/
• CommonGround/kernel/
• CommonGround/infra/
• CommonGround/sdk/
• CommonGround/adapters/
• CommonGround/service/
• Integrations/nanobot/
• tests/

Common Commands

Setup:

git submodule update --init --recursive
uv sync

Reset the database:

PG_DSN=postgresql://USER:PASSWORD@HOST:PORT/DBNAME uv run -m scripts.setup.reset_db

Run the service:

PG_DSN=postgresql://USER:PASSWORD@HOST:PORT/DBNAME uv run cg service run

Compile check:

uv run python -m compileall CommonGround Integrations tests

Full tests:

PG_DSN=postgresql://USER:PASSWORD@HOST:PORT/DBNAME uv run --with pytest python -m pytest tests -q

Focused mainline tests:

uv run --with pytest python -m pytest tests/test_agent_only_service.py tests/test_cg_cli.py tests/test_leaf_worker_main.py tests/test_nanobot_bridge.py -q

Testing Notes

The pytest configuration creates isolated test databases per worker and resets each database per test. Parallel file execution should be safe when tests use tests/conftest.py and tests/pg_support.py.