natsnet/docs/plans/2026-02-27-agents-md-design.md

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.