# 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`