detections/.cursor/CODEX_CONTEXT.md

Codex Context Bridge

This file is a compact compatibility layer for Codex. It explains how the repository uses .cursor/, where project memory lives, and what should be read first in a new chat.

First Read Order

When starting a new Codex session in this repository, read in this order:

1. AGENTS.md
2. .cursor/CODEX_CONTEXT.md
3. _docs/_autopilot_state.md
4. The skill file relevant to the user's request under .cursor/skills/*/SKILL.md
5. Only the _docs/ artifacts and .cursor/rules/*.mdc files relevant to that request

Do not bulk-read all of _docs/ or all skill files unless the task truly needs it.

Mental Model

• .cursor/ is the workflow engine, policy layer, and skill library
• _docs/ is the persisted working memory for the project
• src/, tests/, e2e/, and related runtime files are the implementation layer

For Codex, the important distinction is:

• .cursor/ tells you how the team wants work to happen
• _docs/ tells you what has already been decided or completed

Project Snapshot

• Product: Azaion.Detections
• Type: Python/Cython microservice for aerial object detection
• API: FastAPI + SSE
• Engines: TensorRT on compatible NVIDIA GPUs, ONNX Runtime fallback
• Main code areas: src/, tests/, e2e/, scripts/
• Workflow memory: _docs/

Relevant documented architecture:

• 4 components: Domain, Inference Engines, Inference Pipeline, API
• 10 documented modules under _docs/02_document/modules/
• External services: Loader service, Annotations service

Current Workflow State

As of 2026-04-15, the persisted workflow state says:

• Flow: existing-code
• Current step: 2
• Current step name: Test Spec
• Current status: in_progress
• Current sub-step: Phase 3 - Test Data Validation Gate

Important rollback note from _docs/_autopilot_state.md:

• On 2026-04-10, the workflow was rolled back from Step 8 (New Task) to Step 2 (Test Spec)
• Reason: expected-result artifacts were incomplete for verification

Concrete blocker confirmed from current files:

• _docs/00_problem/input_data/expected_results/results_report.md still contains ? for most expected detection counts
• Per-file expected-result CSVs for non-empty datasets are header-only
• That means black-box tests cannot verify detection correctness yet

Practical unblocker:

1. Populate the expected-result CSVs for the non-empty image/video fixtures
2. Replace ? counts in results_report.md with real values
3. Re-run or continue the test-spec workflow from Phase 3

Cursor Asset Map

Core entry points

• .cursor/README.md: high-level overview of the whole Cursor system
• .cursor/skills/autopilot/SKILL.md: orchestrator contract
• .cursor/skills/autopilot/flows/existing-code.md: active flow for this repository
• .cursor/skills/autopilot/protocols.md: decision, retry, and re-entry rules
• .cursor/agents/implementer.md: only defined subagent

Rules

Always-check rules:

• .cursor/rules/meta-rule.mdc
• .cursor/rules/techstackrule.mdc
• .cursor/rules/git-workflow.mdc
• .cursor/rules/quality-gates.mdc

Highly relevant contextual rules for this repo:

• .cursor/rules/python.mdc
• .cursor/rules/testing.mdc
• .cursor/rules/docker.mdc
• .cursor/rules/cursor-meta.mdc

Other rules exist for security, trackers, OpenAPI, React, Rust, SQL, and .NET. Read them only if the task touches those domains.

Skills Index

Use this table as the fast map instead of opening every skill up front.

Skill	Primary use	Main outputs
autopilot	Continue the end-to-end workflow	state progression in _docs/_autopilot_state.md
problem	Gather or refine the problem definition	_docs/00_problem/
research	Investigate solutions or unknowns	_docs/01_solution/ or standalone research folder
plan	Architecture, components, risks, tests, epics	_docs/02_document/
test-spec	Black-box test specifications and test runners	_docs/02_document/tests/, scripts/run-tests.sh, scripts/run-performance-tests.sh
decompose	Break plan or tests into atomic tasks	_docs/02_tasks/
implement	Batch orchestration of coding tasks	_docs/03_implementation/ plus code changes
test-run	Execute and diagnose test suites	test results and pass/fail guidance
code-review	Review implemented batches against specs	review report and verdict
new-task	Plan new functionality for existing code	_docs/02_tasks/todo/ and optional _docs/02_task_plans/
refactor	Structured refactoring with safety checks	_docs/04_refactoring/
security	Security audit and OWASP-style review	_docs/05_security/
document	Reverse-engineer or update docs from code	_docs/02_document/ and related problem/solution docs
deploy	Containerization, CI/CD, observability	_docs/04_deploy/
retrospective	Review implementation metrics and trends	_docs/06_metrics/
ui-design	UI mockups and design system artifacts	_docs/02_document/ui_mockups/

Agents

Defined agent:

• implementer
  • File: .cursor/agents/implementer.md
  • Role: implement one task spec with tests and AC verification
  • Invoked by: implement skill

No other .cursor/agents/ definitions are currently present.

Codex Operating Notes

When the user asks for Cursor-style continuation

If the user says things like:

• "continue autopilot"
• "what's next"
• "continue workflow"
• "/autopilot"

then:

1. Read _docs/_autopilot_state.md
2. Read .cursor/skills/autopilot/SKILL.md
3. Read .cursor/skills/autopilot/protocols.md
4. Read the active flow file
5. Read only the specific downstream skill file needed for the current step

When the user asks for direct coding help

You do not need to force the full Cursor workflow. Work directly in the codebase, but still:

• respect .cursor/rules/*.mdc
• use _docs/ as authoritative project memory
• preserve alignment with existing task specs and documented architecture when relevant

Context discipline

• Prefer progressive loading over reading everything
• Treat disk artifacts as the source of truth, not prior chat history
• Cross-check state file claims against actual files when something seems inconsistent

Most Relevant Files For This Repo

• AGENTS.md
• .cursor/CODEX_CONTEXT.md
• .cursor/README.md
• .cursor/skills/autopilot/SKILL.md
• .cursor/skills/autopilot/flows/existing-code.md
• .cursor/skills/test-spec/SKILL.md
• .cursor/agents/implementer.md
• _docs/_autopilot_state.md
• _docs/00_problem/
• _docs/01_solution/solution.md
• _docs/02_document/
• _docs/02_tasks/

Short Version

If you only have a minute:

• This repo uses Cursor as a workflow framework and _docs/ as persistent memory
• The project is already documented and mid-workflow
• The current workflow is blocked in test-spec because expected-result data is incomplete
• For future Codex chats, start with AGENTS.md, this file, and _docs/_autopilot_state.md