# AGENTS.md Design

## Purpose

Create an `AGENTS.md` file at the project root for OpenAI Codex agents working on this codebase. The file provides project context, PortTracker CLI reference, porting workflow guidance, and pointers to .NET coding standards.

## Target

OpenAI Codex — follows Codex's AGENTS.md discovery conventions (root-level, markdown format, under 32KB).

## Structure Decision

**Flat single-file** at project root. The project information is tightly coupled — PortTracker commands are needed regardless of which directory Codex is editing. A single file keeps everything in context for every session.

## Sections

1. **Project Summary** — What the project is, where Go source and .NET code live
2. **Folder Layout** — Directory tree with annotations
3. **Build and Test** — Commands to build, run unit tests, run filtered tests, run integration tests
4. **.NET Coding Standards** — Pointer to `docs/standards/dotnet-standards.md` with critical rules inlined (forbidden packages, naming, testing framework)
5. **PortTracker CLI** — Full command reference: querying, updating, audit verification, valid statuses, batch syntax
6. **Porting Workflow** — Step-by-step: finding work, implementing features, implementing tests, post-completion checklist
7. **Go to .NET Translation Reference** — Quick-reference table for common Go-to-.NET pattern translations

## Size

~3.5KB — well within Codex's 32KB default limit.

<!-- Last verified against codebase: 2026-02-27 -->