From 1d30b7c9310fe0d287b4352d1ef496d34e0cb533 Mon Sep 17 00:00:00 2001 From: Olivier Cots Date: Thu, 30 Jul 2026 15:57:05 +0200 Subject: [PATCH] docs(agents): add CLAUDE.md/AGENTS.md navigation guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the agent navigation guide used across sibling control-toolbox packages, adapted to OptimalControl's actual shape: a single flat module (no ext/, no submodule split) that re-exports the ecosystem's public API via `@reexport import Pkg: sym` in src/imports/*.jl — the one place `import` is intentional, per the Handbook's using-only rule everywhere else. Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 116 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..f75fc82b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,58 @@ +# OptimalControl.jl — Agent Navigation Guide + +Quick-reference for any agent working on this repository. + +--- + +## Repository Layout + +OptimalControl is the ecosystem's user-facing DSL package: a single flat module that +orchestrates and re-exports the lower-level control-toolbox packages (CTBase, CTModels, +CTLie, CTDirect, CTSolvers, CTFlows). It does not follow the "one submodule per +responsibility" layout used by sibling packages. + +```text +src/imports/ # Per-dependency reexports (`@reexport import Pkg: sym`) — builds the public API +src/helpers/ # Internal helpers (routing, completion, registry, printing) +src/solve/ # `solve` dispatch: mode detection, descriptive/explicit paths +test/suite/ # Test suite: organised by functionality, not by src/ layout +docs/ # Documentation site (DocumenterVitepress) +``` + +There is no `ext/`: optional backends (ADNLPModels, ExaModels, AD) are armed by +dependency presence, wired in `src/imports/*.jl`, not weak-dependency extensions. + +--- + +## Developer Resources + +Design philosophy, operational rules, plan templates, and CI/CD conventions live in the +[control-toolbox Handbook](https://github.com/control-toolbox/Handbook): + +| Topic | Link | +| --- | --- | +| Code philosophy (modules, types/traits, exceptions, docstrings, testing, docs) | [`PHILOSOPHY.md`](https://raw.githubusercontent.com/control-toolbox/Handbook/refs/heads/main/PHILOSOPHY.md) | +| Operational rules (tests, coverage, docs, git) | [`RULES.md`](https://raw.githubusercontent.com/control-toolbox/Handbook/refs/heads/main/RULES.md) | +| Plan template | [`PLAN.md`](https://raw.githubusercontent.com/control-toolbox/Handbook/refs/heads/main/PLAN.md) | +| CI/CD workflows (centralized reusable workflows, label-gated triggers) | [`WORKFLOWS.md`](https://raw.githubusercontent.com/control-toolbox/Handbook/refs/heads/main/WORKFLOWS.md) | + +--- + +## Key Conventions + +- **Exports a curated public API** — unlike sibling packages ("no top-level exports"), + OptimalControl is the ecosystem's DSL entry point: it re-exports selected symbols from + CTBase, CTModels, CTLie, CTDirect, CTSolvers, CTFlows. +- **`@reexport import Pkg: sym`** — the one place `import` is intentional in this + ecosystem: `src/imports/*.jl` builds the exported surface this way; everywhere else, + qualified `using` only (`using Pkg: Pkg`), never bare `using Pkg`. +- **Fake types at module top-level** — never inside test functions. +- **Structured errors** — seven typed exceptions under `CTException`; pick by the + IncorrectArgument / PreconditionError / NotImplemented rule. +- **Type stability enforced** — hot paths must be `@inferred`-clean, verified with JET; + setup-path dispatch is fine. +- **1-D is a scalar** — a one-dimensional state/control/variable is a `Number`, never a + length-1 vector. +- **Plans before code** — write a plan and confirm with the user before touching files. +- **Docstrings last** — written only after all implementation steps are stable. +- **Never commit or push without explicit user approval.** diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..c29c8178 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,58 @@ +# OptimalControl.jl — Agent Navigation Guide + +Quick-reference for any agent working on this repository. + +--- + +## Repository Layout + +OptimalControl is the ecosystem's user-facing DSL package: a single flat module that +orchestrates and re-exports the lower-level control-toolbox packages (CTBase, CTModels, +CTLie, CTDirect, CTSolvers, CTFlows). It does not follow the "one submodule per +responsibility" layout used by sibling packages. + +```text +src/imports/ # Per-dependency reexports (`@reexport import Pkg: sym`) — builds the public API +src/helpers/ # Internal helpers (routing, completion, registry, printing) +src/solve/ # `solve` dispatch: mode detection, descriptive/explicit paths +test/suite/ # Test suite: organised by functionality, not by src/ layout +docs/ # Documentation site (DocumenterVitepress) +``` + +There is no `ext/`: optional backends (ADNLPModels, ExaModels, AD) are armed by +dependency presence, wired in `src/imports/*.jl`, not weak-dependency extensions. + +--- + +## Developer Resources + +Design philosophy, operational rules, plan templates, and CI/CD conventions live in the +[control-toolbox Handbook](https://github.com/control-toolbox/Handbook): + +| Topic | Link | +| --- | --- | +| Code philosophy (modules, types/traits, exceptions, docstrings, testing, docs) | [`PHILOSOPHY.md`](https://github.com/control-toolbox/Handbook/blob/main/PHILOSOPHY.md) | +| Operational rules (tests, coverage, docs, git) | [`RULES.md`](https://github.com/control-toolbox/Handbook/blob/main/RULES.md) | +| Plan template | [`PLAN.md`](https://github.com/control-toolbox/Handbook/blob/main/PLAN.md) | +| CI/CD workflows (centralized reusable workflows, label-gated triggers) | [`WORKFLOWS.md`](https://github.com/control-toolbox/Handbook/blob/main/WORKFLOWS.md) | + +--- + +## Key Conventions + +- **Exports a curated public API** — unlike sibling packages ("no top-level exports"), + OptimalControl is the ecosystem's DSL entry point: it re-exports selected symbols from + CTBase, CTModels, CTLie, CTDirect, CTSolvers, CTFlows. +- **`@reexport import Pkg: sym`** — the one place `import` is intentional in this + ecosystem: `src/imports/*.jl` builds the exported surface this way; everywhere else, + qualified `using` only (`using Pkg: Pkg`), never bare `using Pkg`. +- **Fake types at module top-level** — never inside test functions. +- **Structured errors** — seven typed exceptions under `CTException`; pick by the + IncorrectArgument / PreconditionError / NotImplemented rule. +- **Type stability enforced** — hot paths must be `@inferred`-clean, verified with JET; + setup-path dispatch is fine. +- **1-D is a scalar** — a one-dimensional state/control/variable is a `Number`, never a + length-1 vector. +- **Plans before code** — write a plan and confirm with the user before touching files. +- **Docstrings last** — written only after all implementation steps are stable. +- **Never commit or push without explicit user approval.**