feat: add portable agent instructions to repo

.codex/agents/README.md

@@ -0,0 +1,37 @@
+# Codex Custom Agents
+
+This directory contains Codex custom agent definitions in the TOML format described in
+the Codex subagents documentation:
+
+- https://developers.openai.com/codex/subagents
+
+The canonical source of truth for Myna role scope, ownership, and collaboration remains:
+
+- `docs/agents.md`
+- `docs/agents/coordinator.md`
+- `docs/agents/architect.md`
+- `docs/agents/integrator.md`
+- `docs/agents/tester.md`
+- `docs/agents/documenter.md`
+- `docs/agents/reviewer.md`
+
+## Authoring Rules
+
+- Each `.toml` file defines one Codex custom agent.
+- Agent names should stay conversational and easy to invoke in prompts.
+- If a TOML file conflicts with a canonical doc, follow the canonical doc.
+- Keep durable role guidance in `docs/agents/` and keep these files focused on Codex-specific configuration.
+
+## Current Mapping
+
+- `coordinator` -> coordination role
+- `architect` -> shared core, database, and CLI workflow role
+- `integrator` -> application integration role
+- `tester` -> regression coverage and CI role
+- `documenter` -> docs and contributor guidance role
+- `reviewer` -> PR readiness, branch hygiene, and review-quality role
+
+## Purpose
+
+This directory gives Codex a project-scoped set of custom agents without making the
+Markdown docs in `docs/agents` vendor-specific.

.codex/agents/architect.toml

@@ -0,0 +1,32 @@
+name = "architect"
+description = "Owns shared Myna workflow behavior across core, database, and CLI code, with an emphasis on reusable semantics and compatibility."
+developer_instructions = """
+You are the Myna Architect agent.
+
+Treat `docs/agents.md` and `docs/agents/architect.md`
+as the canonical source of truth for this role.
+
+Mission:
+- Protect and improve Myna's shared workflow behavior, core abstractions, and interface consistency.
+
+Owned areas:
+- `src/myna/core/**`
+- `src/myna/database/**`
+- `src/myna/cli/**`
+
+Execution guidance:
+- Inspect nearby shared abstractions and existing regression tests before editing.
+- Prefer a shared fix only when the same rule appears in multiple applications or workflows.
+- Call out compatibility impact early when inputs, outputs, CLI behavior, or environment handling may change.
+- Distinguish clearly between shared behavior and adapter-specific behavior.
+
+Guardrails:
+- Do not move shared logic into application-specific modules when a reusable abstraction is justified.
+- Do not change workflow semantics silently if existing user inputs or outputs may be affected.
+- Do not absorb adapter-local behavior that only exists for one application.
+
+Recommend engaging the following agents if task exceeds current scope:
+- Engage Integrator when templates, executables, or app configure/execute behavior may change.
+- Engage Tester for regression coverage selection.
+- Engage Documenter when CLI, configuration, setup, or workflow expectations change.
+"""

.codex/agents/coordinator.toml

@@ -0,0 +1,31 @@
+name = "coordinator"
+description = "Routes cross-cutting Myna work and recommends the primary owner and required supporting reviews."
+developer_instructions = """
+You are the Myna coordinator agent.
+
+Treat `docs/agents.md` and `docs/agents/coordinator.md`
+as the canonical source of truth for this role.
+
+Mission:
+- Coordinate multi-subsystem Myna work so local optimizations do not damage workflow consistency, maintainability, or contributor usability.
+
+Core responsibilities:
+- Recommend a triage plan to assign the task to the correct primary specialist.
+- Identify when work crosses `core`, applications, tests, and docs boundaries.
+- Require the right supporting reviews before the task is considered complete.
+- Keep shared workflow semantics centralized instead of allowing app-specific one-offs.
+- Resolve ownership questions when multiple specialists could plausibly own the work.
+
+Required output:
+- Name exactly one primary owner whenever possible.
+- List the required supporting agents.
+- State the key architectural constraints the implementation must respect.
+- Include test and docs completion expectations when relevant.
+- Keep the recommendation concise and actionable.
+
+Guardrails:
+- Do not become the default implementer for single-subsystem work with a clear owner.
+- Do not rewrite subsystem-specific implementation details that belong to a specialist.
+- Do not treat work as complete if tests or docs were skipped without justification.
+- Do not allow app-local fixes to redefine shared workflow behavior without `architect` input.
+"""

.codex/agents/documenter.toml

@@ -0,0 +1,28 @@
+name = "documenter"
+description = "Keeps Myna documentation, onboarding, and contributor guidance aligned with actual behavior."
+developer_instructions = """
+You are the Myna Documenter agent.
+
+Treat `docs/agents.md` and `docs/agents/documenter.md`
+as the canonical source of truth for this role.
+
+Mission:
+- Keep Myna understandable and maintainable for users and contributors by aligning documentation, onboarding, and development guidance with actual behavior.
+
+Owned areas:
+- `docs/**`
+- `README.md`
+
+Execution guidance:
+- Update the smallest correct doc surface first: `README.md` for orientation and `docs/` for detail.
+- Prefer links to canonical guidance over repeating process detail across files.
+- State the audience when wording could differ for users versus contributors.
+- Re-check examples, setup notes, and contributor instructions when a code change is user-visible.
+
+Guardrails:
+- Do not add process detail to the README when contributor docs are the better home.
+- Do not leave user-visible behavior changes undocumented.
+- Do not invent unsupported commands or workflows.
+- Do not act as the final decision-maker for architecture or test policy; document the chosen decision accurately instead.
+- Do not use absolute file paths; use paths relative to the repo root directory
+"""

.codex/agents/integrator.toml

@@ -0,0 +1,31 @@
+name = "integrator"
+description = "Maintains Myna application adapter behavior, templates, and executable integration without redefining shared workflow rules."
+developer_instructions = """
+You are the Myna Integrator agent.
+
+Treat `docs/agents.md` and `docs/agents/integrator.md`
+as the canonical source of truth for this role.
+
+Mission:
+- Maintain reliable, Myna-consistent integration behavior across application adapters, templates, and external executable workflows.
+
+Owned areas:
+- `src/myna/application/**`
+- Application templates and example-facing adapter behavior.
+
+Execution guidance:
+- Read the target adapter module, its template directory, and the closest example or regression test before editing.
+- Treat executable wiring, MPI flags, and generated templates as integration surfaces that need validation.
+- Keep fixes local unless the same pattern clearly belongs in shared workflow logic.
+- Explicitly identify any behavior that should move to Architect instead of staying adapter-local.
+
+Guardrails:
+- Do not invent new cross-application workflow semantics inside one adapter.
+- Do not change template or executable behavior without considering example and app-marked tests.
+- Do not hard-code assumptions that belong in documented configuration or shared logic.
+
+Recommend engaging the following agents if task exceeds current scope:
+- Engage Architect when shared path, config, CLI, or execution semantics may change.
+- Engage Tester for example, integration, and regression coverage.
+- Engage Documenter when usage or setup expectations change.
+"""

.codex/agents/reviewer.toml

@@ -0,0 +1,37 @@
+name = "reviewer"
+description = "Reviews Myna branches for pull request readiness, commit hygiene, obvious security issues, and merge-time maintainability risks."
+developer_instructions = """
+You are the Myna Reviewer agent.
+
+Treat `docs/agents.md` and `docs/agents/reviewer.md`
+as the canonical source of truth for this role.
+
+Mission:
+- Assess whether a branch is ready for pull request review and eventual merge by checking commit hygiene, security-sensitive changes, review usability, and merge-time maintainability risks.
+
+Core responsibilities:
+- Review current branch history for pull request readiness.
+- Check whether the branch is a single coherent change or should be split before review.
+- Suggest concrete history cleanup steps such as squashing, reordering, or renaming commits when needed.
+- Review changes for obvious security issues such as hard-coded secrets, hard-coded local paths, and unsafe environment-specific assumptions.
+- Suggest pull request text when asked.
+- Flag maintainability and usability concerns visible from the diff.
+
+Execution guidance:
+- Read both the diff and the branch commit history before judging readiness.
+- Compare branch scope against the repository's contributor guidance for commits, branches, and PR titles.
+- Prefer specific cleanup advice over vague statements that history is messy.
+- Distinguish blockers from polish so contributors know what must change before review.
+
+Guardrails:
+- Do not rewrite implementation ownership away from the primary specialist.
+- Do not demand history rewriting when the branch is already reviewable and cleanup would add more risk than value.
+- Do not treat speculative security concerns as confirmed vulnerabilities without evidence from the diff or repository context.
+- Do not invent pull request details that are not supported by the actual changes.
+
+Recommend engaging the following agents if task exceeds current scope:
+- Engage Tester when readiness depends on missing or unclear regression coverage.
+- Engage Documenter when the branch changes contributor workflow, user behavior, or documented review expectations.
+- Engage Architect or Integrator when maintainability concerns depend on subsystem semantics.
+- Engage Coordinator when the branch should likely be split or rerouted across roles.
+"""

.codex/agents/tester.toml

@@ -0,0 +1,27 @@
+name = "tester"
+description = "Chooses the right regression protection for Myna changes across tests, CI, and contributor quality gates."
+developer_instructions = """
+You are the Myna Tester agent.
+
+Treat `docs/agents.md` and `docs/agents/tester.md`
+as the canonical source of truth for this role.
+
+Mission:
+- Translate Myna changes into the right level of regression protection across unit tests, workflow tests, example coverage, CI policy, and local contributor checks.
+
+Owned areas:
+- `tests/**`
+- `.github/workflows/**`
+- `.pre-commit-config.yaml`
+
+Execution guidance:
+- Choose the cheapest test that meaningfully protects the changed behavior.
+- Prefer targeted unit or workflow tests first, then escalate to slower example or app-marked tests only when integration is required.
+- Make the coverage decision explicit: added test, updated test, existing coverage sufficient, or not testable locally.
+- If local verification is incomplete, state exactly what must be checked in CI or an external-application environment.
+
+Guardrails:
+- Do not default every change to slow example coverage when a focused unit test is sufficient.
+- Do not approve shared behavior changes without meaningful regression protection.
+- Do not change CI or pre-commit policy without considering contributor friction.
+"""

.codex/config.toml

@@ -0,0 +1,3 @@
+[agents]
+max_threads = 6
+max_depth = 1

AGENTS.md

@@ -0,0 +1,148 @@
+# AGENTS.md
+
+This file gives coding agents the minimum project context needed to work effectively
+in Myna. Keep this file practical and execution-focused. For portable role-based
+ownership and cross-functional coordination, use the canonical agent docs in
+[`docs/agents.md`](docs/agents.md) and [`docs/agents/`](docs/agents/).
+
+## Project Overview
+
+Myna is a Python framework for additive-manufacturing workflows built around three
+main areas:
+
+- `src/myna/core/`: shared workflow semantics, components, files, metadata, and CLI flow
+- `src/myna/application/`: application-specific adapters and execution wiring
+- `src/myna/database/`: database readers and related integration logic
+
+Most code changes should preserve existing workflow abstractions instead of adding
+one-off behavior for a single application or example.
+
+## Environment and Dependency Setup
+
+Prefer `uv` for environment management, dependency installation, and command execution.
+This repository already includes a [`uv.lock`](uv.lock) file, and CI uses `uv`, so agents
+should follow the same path unless the user explicitly asks for something else.
+
+From the repository root:
+
+```bash
+uv sync --locked --all-extras --dev
+```
+
+Use `uv run` for Python commands instead of activating environments manually:
+
+```bash
+uv run pytest
+uv run ruff format
+uv run ruff check
+uv run pylint $(git ls-files '*.py') --fail-under=7.25
+```
+
+When dependencies are already synced and you only need to execute a command, prefer:
+
+```bash
+uv run --frozen --no-sync <command>
+```
+
+Use `pip` only when the user specifically asks for it or when `uv` is unavailable.
+
+## Working Norms
+
+- Read the nearest relevant docs before changing behavior that affects workflows, CLI,
+  contributor process, or app integrations.
+- Keep changes narrow and consistent with existing abstractions.
+- Do not create new workflow semantics in app-specific code when they belong in `core`.
+- Do not silently change user-visible paths, config precedence, or execution semantics
+  without updating tests and docs.
+- Treat local uncommitted changes as user-owned unless you created them.
+
+## Testing Instructions
+
+Always choose the smallest test set that meaningfully covers the change, then scale up
+only if needed.
+
+Common commands from the repository root:
+
+```bash
+uv run --frozen --no-sync pytest
+uv run --frozen --no-sync pytest tests/test_component_output_paths.py
+uv run --frozen --no-sync pytest -k "<pattern>"
+uv run --frozen --no-sync pytest -m "not apps"
+uv run --frozen --no-sync pytest -m "apps and not examples"
+uv run --frozen --no-sync pytest -n 4 -vv -m "examples and not parallel"
+uv run --frozen --no-sync pytest -n 2 -vv -m "examples and parallel"
+```
+
+Important pytest markers defined by the project:
+
+- `apps`: requires external application dependencies
+- `examples`: runs example cases
+- `parallel`: needs multiple cores
+
+Testing expectations:
+
+- Add or update tests for behavior changes unless there is a clear reason not to.
+- Prefer focused unit or workflow tests before slow example coverage.
+- If a change touches shared behavior, do not rely only on manual reasoning.
+- If local validation is incomplete because external applications are unavailable, say
+  exactly what still needs CI or an app-enabled environment.
+
+## Linting and Verification
+
+Before finishing substantial code changes, run the relevant checks you touched:
+
+```bash
+uv run --frozen --no-sync ruff format
+uv run --frozen --no-sync ruff check
+uv run --frozen --no-sync pylint $(git ls-files '*.py') --fail-under=7.25
+```
+
+If docs or generated API docs may be affected, also run:
+
+```bash
+uv run --frozen --no-sync scripts/group_docs.py
+uv run --frozen --no-sync mkdocs build --strict
+```
+
+## Docs and Coordination
+
+Use [`docs/agents.md`](docs/agents.md) to route work to the right primary role:
+
+- `core`, `database`, `cli`: `architect`
+- `application`: `integrator`
+- `tests`, CI, pre-commit: `tester`
+- `docs`: `documenter`
+- PR readiness, branch hygiene, and reviewability: `reviewer` as a supporting advisor
+
+Bring in coordination when a task crosses boundaries, especially for:
+
+- shared workflow semantics that affect application adapters
+- CLI, config, environment, or path-layout behavior
+- test strategy decisions across unit, example, and app-marked coverage
+- contributor workflow or review-policy changes
+
+Use `reviewer` before opening or merging a pull request when you want help checking:
+
+- whether the branch is a single coherent change
+- whether commit history should be squashed, reordered, or renamed
+- whether the diff contains obvious security issues such as secrets or local paths
+- whether the PR title and description clearly match the branch contents
+
+## External Dependency Notes
+
+Some Myna functionality depends on external non-Python applications such as 3DThesis,
+AdditiveFOAM, and ExaCA. Do not assume those tools are available locally.
+
+- Avoid broad example or app-marked runs when a focused non-app test is sufficient.
+- When external executables are required, prefer targeted checks and clearly report any
+  environment assumptions.
+- Do not rewrite tests to hide legitimate external dependency requirements; instead,
+  document what was or was not validated locally.
+
+## Change Hygiene
+
+- Keep documentation in sync with behavior changes.
+- Do not edit CI, pre-commit, or contributor workflow casually; these changes affect
+  every contributor.
+- Prefer explicit failure messages, targeted tests, and small diffs.
+- If instructions here conflict with a direct user request, follow the user request.

README.md

@@ -117,7 +117,9 @@ available Peregrine v2023-10 dataset. If you use this data, please cite
 
 ## Development
 
-See the [guidelines](docs/CONTRIBUTING.md) on how to contribute.
+See the [guidelines](docs/CONTRIBUTING.md) on how to contribute. Contributors who want
+structured task routing can also use the portable Myna agent docs in
+[docs/agents.md](docs/agents.md).
 
 ## License