ephemeral-buffer-mcp: Instructions file for Codex

Agent and Contributor Guide

This file contains project-level guidance for any coding agent or contributor. It is intentionally independent of a particular editor, coding-agent product, MCP client, or operating environment.

Project workflow

• Keep main protected. Make changes on a development branch and open a pull request; do not push directly to main.
• Ensure the pull request CI checks pass before merging. The repository permits maintainer overrides for exceptional cases, but those are exceptions.
• Preserve the linear history policy. When merging, use a rebase-style merge without squashing unless the repository owner explicitly chooses otherwise.
• Remove merged development branches locally and remotely, then verify that the local checkout is clean and synchronized with origin/main.
• Keep commits focused and explain behavior changes in the commit message.

Project-local skills

• Keep reusable EB-specific Codex skills in the tracked skills/<skill-name>/SKILL.md structure. The canonical activity report skill is skills/eb-activity-summary/SKILL.md.
• Generated reports such as /tmp/activity-summary.html are local output and must not be committed.
• Install project-local skills into a Codex skill root separately when automatic discovery outside this repository is needed; do not commit machine-specific symlinks or caches.

Local validation

Create the supported development environment with the committed Python 3.12 development lock:

python3.12 -m venv .venv
.venv/bin/python -m pip install --require-hashes -r requirements-dev-lock-py312.txt
.venv/bin/python -m pip install --no-deps -e .

Run the focused suite and application coverage with deterministic test embeddings in an isolated per-command namespace:

EPHEMERAL_TEST_EMBEDDINGS=1 ./scripts/with-test-env.sh .venv/bin/python -m coverage run \
  --source=ephemeral_buffer_mcp -m unittest \
  tests.unit.test_admission tests.benchmarks.test_benchmark_concurrency tests.benchmarks.test_benchmark_effectiveness \
  tests.benchmarks.test_benchmark_latency tests.benchmarks.test_benchmark_routing tests.benchmarks.test_benchmark_prefetch \
  tests.benchmarks.test_benchmark_semantic_index tests.benchmarks.test_benchmark_semantic_memory tests.benchmarks.test_benchmark_warmup \
  tests.benchmarks.test_benchmark_relevance tests.benchmarks.test_benchmark_agent_ab tests.benchmarks.test_benchmark_agent_ab_fixtures \
  tests.benchmarks.test_benchmark_agent_ab_repository_fixture tests.benchmarks.test_benchmark_agent_ab_baseline \
  tests.benchmarks.test_run_codex_agent_ab tests.tooling.test_release_checks tests.tooling.test_release_benchmark_timeout \
  tests.benchmarks.test_benchmark_admission tests.benchmarks.test_workload_results \
  tests.benchmarks.test_compare_workload_results tests.benchmarks.test_list_workload_results tests.tooling.test_ci_workflow \
  tests.unit.test_mcpserver_adapter tests.unit.test_semantic_index tests.unit.test_engine tests.unit.test_embedding_backend tests.unit.test_capture_utils tests.unit.test_config \
  tests.unit.test_cli tests.unit.test_socket_protocol tests.unit.test_server tests.unit.test_metrics \
  tests.unit.test_logging_utils tests.unit.test_execution tests.unit.test_execution_server \
  tests.unit.test_transport_decomposition
.venv/bin/python -m coverage report -m --fail-under=100
EPHEMERAL_TEST_EMBEDDINGS=1 ./scripts/with-test-env.sh .venv/bin/python -m unittest tests.integration.test_e2e_pipe