# AGENTS.md — Numu Angels AI entry point (thin router) > **Primary, tool-neutral adapter** for any AI (Claude, Codex, Cursor, MCP clients, or others) working in this repository. This file is a **router only** — it holds **no** project knowledge. All architecture, features, APIs, database, business rules, and the mandatory workflow live in the **Engineering Platform** (the Central Knowledge System). Do not add project knowledge here; keep it thin. ## Step 0 — Locate the Engineering Platform (do this first) The canonical knowledge is **not** in this repository. It lives in its own Azure DevOps repository: ``` https://dev.azure.com/numuinvestment/numu/_git/numu-engineering-platform ``` The local folder is only a **working copy**. If you do not have it, clone it as a **sibling** of this repository — the trailing folder name matters: ```bash # from the parent folder that contains this repository git clone https://dev.azure.com/numuinvestment/numu/_git/numu-engineering-platform engineering-platform ``` Find it in this order: 1. **Sibling checkout (default):** `../engineering-platform/` — this repo and the platform are cloned side by side. 2. **Same sibling under the repository's own name** (what a plain `git clone` produces): `../numu-engineering-platform/`. 3. **Explicit override:** the path in the `ENGINEERING_PLATFORM_PATH` environment variable, if set. 4. **If none resolves → STOP.** Report that the canonical `engineering-platform` repository/path could not be found and **request its location** (or clone it with the command above). Do **not** proceed with high-risk or architecture-affecting work, and do **not** fall back to this repo's legacy `docs/ai/` as an equivalent (see [Legacy handling](#legacy-handling)). Confirm discovery by checking that `/01-foundation/ai-workflow.md` exists. ## Step 0b — Synchronize the platform (MANDATORY, every task) The platform is a **shared, multi-developer repository**. A stale local copy means working against out-of-date laws, workflow gates and safety policies. - **Before starting any task — pull:** `cd && git pull` - **After changing anything inside the platform — commit AND push.** A documentation update that stays on one workstation has not been delivered: Gate 6 is not satisfied until the change is pushed to the canonical repository above, where every other developer and AI agent reads it. - **Never** hand-copy platform files between machines or into this repository. The repository is the only distribution channel. ## Step 1 — Load the canonical workflow BEFORE any task work Read, in this order: 1. `/01-foundation/ai-workflow.md` — the **mandatory, tool-neutral 7-gate execution loop** (intake → context loading → impact analysis → implement → verify → doc sync → report). This is binding. 2. `/01-foundation/ai-constitution.md` — the binding engineering laws (loaded/obeyed per Constitution §10.1). Everything below simply enforces what `ai-workflow.md` already defines — **it is the authority; this router does not restate its rules.** ## Step 2 — Load the project index `/02-projects/numu-angels/README.md` — the Numu Angels knowledge base entry (features · api · database · modules · architecture · integrations · ai-agents · workflows · decisions). ## Step 3 — Load task-scoped knowledge (only what the change needs) Follow the **deterministic loading order + change-type→knowledge matrix** in `ai-workflow.md` Gate 2. Load the relevant **Feature**, **API**, **Database**, **ADR/decision**, and **standard** documents for the task type — then read the **current source code last**, as the final evidence of what the system does. ## Mandatory gates (enforced by `ai-workflow.md` — obey them here) Do not skip any. Details and the high-risk list are in `ai-workflow.md`; this is the checklist: 1. **Task ID** — assign or confirm one before starting. 2. **Verify docs against current source** — documentation is the navigation/impact baseline; source is the final evidence of *what is*. Report + correct drift within task scope; never guess business intent from code. 3. **Pre-implementation impact analysis (Gate 3)** — a written, source-verified impact report before implementing. 4. **High-risk approval stop** — for any change on the canonical high-risk list (destructive DB, breaking API contract, business-rule/canonical-service change, permissions/security, deletion/retirement, shared-invariant, locked ADR/DR, deploy-ordering), **stop and get accountable-owner approval before implementing**. Never self-approve. 5. **Documentation synchronization (Gate 6)** — update every affected Engineering-Platform KB doc in the same change; **or** record an **evidence-backed** "No documentation impact" (cite the files/impact evidence — a bare assertion is not acceptable). 6. **Completion report (Gate 7)** — use `/06-templates/completion-report.md`; a task is not complete without it. 7. **Preserve unrelated changes** — never silently expand scope or disturb other working-tree changes. ## Knowledge-location failure behavior If the Engineering Platform cannot be located or read: - Do **not** pretend canonical knowledge was loaded. - Do **not** silently use this repo's `docs/ai/` as an equivalent source. - Report the missing canonical repository/path and **request the correct location**. - Before any high-risk or architecture-affecting work, **stop** until the platform is available. Only explicitly authorized, low-risk work that the canonical workflow permits may proceed. ## Legacy handling This repo's `docs/ai/` is **legacy** (pre-migration). It is **not** authoritative and **not** the fallback. It is **not** deleted by this task; its retirement is separate follow-up work tracked under **ADR-0002** in the Engineering Platform. Adapters must route to the platform, not to `docs/ai/`. ## Anti-duplication rule This file (and the tool-specific adapters `CLAUDE.md`, `CODEX.md`, `MCP.md`) are **thin routers**. They must never restate architecture, business rules, workflow steps, the loading order, impact-analysis dimensions, or documentation-sync rules — those live once, in the Engineering Platform. Duplicated knowledge in an adapter is a defect (see `/01-foundation/ai-tool-adapters.md`).