Imported from rafacandido7/racetrace (AGENTS.md). Install upstream with npx skills add rafacandido7/racetrace. Copyright stays with the author.

@/Users/candido/.codex/RTK.md @PROGRESS.md

Agent Guide

Switching models / picking up work? Read PROGRESS.md (imported above) first — it is the single always-current snapshot of milestones, in-flight tasks, next action, and recent commits. It is regenerated automatically (scripts/progress.sh, Stop hook) from the roadmap, .specs tasks, and git.

Project Map

• docs/project/00-roadmap.md defines milestone scope and ordering.
• docs/project/02-architecture.md describes component boundaries.
• docs/project/04-data-flow.md defines Kafka message contracts.
• docs/project/05-observability.md covers the M3 tracing design.
• docs/project/06-running-locally.md explains local Docker workflows.
• docs/milestones/ contains milestone-specific implementation notes.

Current State

• M0 is complete: local Kafka, Redis, SigNoz, and topics are defined in infra/docker-compose.yml.
• M1 is implemented: the Python replayer reads FastF1 data and publishes position and telemetry messages to Kafka.
• M2 is implemented: the Go gap consumer reads position, publishes gap, and uses Redis idempotency.
• M3 is implemented: the replayer and gap consumer propagate W3C traceparent through Kafka and export OpenTelemetry spans to SigNoz.
• The local SigNoz collector uses the static repository config in infra/signoz/collector/otel-collector-config.yaml; do not re-enable OpAMP-managed --manager-config for local development because it can replace the effective pipeline with nop.

Canonical Commands

• Start infra: rtk docker compose -f infra/docker-compose.yml up -d
• Stop infra: rtk docker compose -f infra/docker-compose.yml down
• Validate infra compose: rtk docker compose -f infra/docker-compose.yml config
• Replayer setup: cd replayer && rtk uv sync --locked
• Run replayer locally: cd replayer && rtk uv run racetrace-replayer --race silverstone-2021 --speed 30
• Run replayer in Docker: rtk docker compose -f infra/docker-compose.replayer.yml run --rm --build replayer --race silverstone-2021 --speed 30
• Replayer lint: cd replayer && rtk uv run ruff check .
• Replayer unit tests: cd replayer && rtk uv run pytest tests/unit
• Replayer integration tests: cd replayer && rtk uv run pytest tests/integration
• Replayer E2E tests: cd replayer && rtk uv run pytest tests/e2e
• Gap consumer unit tests: cd consumers/gap && rtk proxy env GOCACHE=/private/tmp/racetrace-go-build go test ./internal/... ./cmd/...
• Gap consumer integration tests: cd consumers/gap && rtk proxy env GOCACHE=/private/tmp/racetrace-go-build GAP_INTEGRATION=1 go test ./tests/integration -count=1 -v
• M1+M2+M3 combined E2E: cd consumers/gap && rtk proxy env GOCACHE=/private/tmp/racetrace-go-build GAP_E2E=1 go test ./tests/e2e -count=1 -v

Post-Implementation Verification

After any massive implementation, run the M1+M2+M3 combined E2E before reporting completion:

cd consumers/gap && rtk proxy env GOCACHE=/private/tmp/racetrace-go-build GAP_E2E=1 go test ./tests/e2e -count=1 -v

Treat "massive implementation" as any broad change that affects service behavior, Kafka contracts, Docker Compose, schemas, replayer/gap consumer code, integration/E2E tests, or multiple project areas. The E2E must validate traceparent on position, telemetry, and gap, with the gap trace ID matching an observed position trace ID and a different span ID. If the command cannot run because Docker, Kafka, Redis, or FastF1 cache/network access is unavailable, report that blocker explicitly instead of presenting the implementation as fully verified.

Fixed Decisions

• Python dependency management uses uv.
• The replayer has a separate Compose file at infra/docker-compose.replayer.yml.
• The replayer Compose service joins the existing external racetrace-net network.
• Kafka messages are JSON and keyed by driver_number.
• M1 publishes only source data. Derived gap/event logic belongs to later consumers.
• M3 tracing propagates traceparent from position into gap; failures to export spans must not block replay or consumption.
• For a clean SigNoz demo after docker compose down -v, start infra, wait for otel-collector:4317 to accept connections, then recreate the gap consumer before running the replayer.
• Controller callbacks remain out of scope until later milestones.

Instruction Fragmentation

Subdirectories may add their own AGENTS.md when they need more specific instructions. The closest AGENTS.md to the edited file complements this root guide and may override it for that subtree.

Skills

@.agents/skills/harness-sync/SKILL.md @.agents/skills/test-guardian/SKILL.md @.agents/skills/racetrace-architecture/SKILL.md