mirror of
https://github.com/azaion/detections.git
synced 2026-04-22 21:46:31 +00:00
Roman Meshko
188 lines
6.9 KiB
Markdown
188 lines
6.9 KiB
Markdown
# 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`
|