diff --git a/.coderabbit.yaml b/.coderabbit.yaml index e46e6feb42..0ebf4abce9 100644 --- a/.coderabbit.yaml +++ b/.coderabbit.yaml @@ -46,6 +46,7 @@ knowledge_base: enabled: true filePatterns: - "AGENTS.md" + - "**/AGENTS.md" - "docs/developers_guide/agent_governance.md" - ".github/copilot-instructions.md" - ".github/instructions/*.instructions.md" diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index afe203f9a9..9bdc8a153b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -7,9 +7,12 @@ the ABACUS development baseline in: - `docs/developers_guide/agent_governance.md` Treat `AGENTS.md` as the short entry point and -`docs/developers_guide/agent_governance.md` as the complete rule source. Review -the pull request diff before general style feedback, and separate blocking -diff-scoped issues from historical or advisory observations. +`docs/developers_guide/agent_governance.md` as the complete rule source. A +module directory under `source/` (e.g., `source/source_esolver/`) may carry its +own `AGENTS.md` with module-specific constraints; read it when working in or +reviewing that directory, and note that it refines the root baseline without +overriding it. Review the pull request diff before general style feedback, and +separate blocking diff-scoped issues from historical or advisory observations. Use the ABACUS review finding format for actionable findings: diff --git a/AGENTS.md b/AGENTS.md index a07c3a5700..cc88419a14 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -93,6 +93,11 @@ rules. Read the complete governance document before making or reviewing changes: - Core C++ implementation lives under `source/`; source additions must be wired through the relevant `CMakeLists.txt`. +- Each module directory under `source/` (e.g., `source/source_esolver/`, + `source/source_io/`) may carry its own `AGENTS.md` describing module-specific + design constraints and conventions. When working inside such a directory, + read and follow its `AGENTS.md` in addition to this file; the module-level + rules refine, but never override, this root file. - INPUT parsing and help metadata live under `source/source_io/`; user-facing INPUT reference is generated from that metadata during the documentation build. diff --git a/docs/developers_guide/agent_governance.md b/docs/developers_guide/agent_governance.md index a11d440d30..9f33db289a 100644 --- a/docs/developers_guide/agent_governance.md +++ b/docs/developers_guide/agent_governance.md @@ -5,6 +5,15 @@ contributors, general AI agents, CodeRabbit, and GitHub CI. `AGENTS.md` is the short entry point; this file is the complete rule source for implementation and review. +## Entry Points + +The repository-root `AGENTS.md` is the short entry point. A module directory +under `source/` (e.g., `source/source_esolver/`, `source/source_io/`) may carry +its own `AGENTS.md` describing module-specific design constraints and +conventions. When working in, or reviewing, such a directory, read the module +file together with the root file; module-level rules refine the root baseline +and never override it. + ## Source Materials The governance rules consolidate project guidance from @mohanchen's coding diff --git a/source/source_esolver/AGENTS.md b/source/source_esolver/AGENTS.md new file mode 100644 index 0000000000..12d450b34a --- /dev/null +++ b/source/source_esolver/AGENTS.md @@ -0,0 +1,15 @@ +# ESolver Module Rules + +`source_esolver` is the cockpit dashboard of ABACUS: it presents the high-level +algorithm workflow, while the low-level implementation details stay "under the +hood" in their owning modules. + +1. `esolver` functions only orchestrate the algorithm flow (e.g., SCF + iteration, relaxation steps). Any computation of a concrete physical + quantity must be implemented in the owning module (e.g., + `source_estate`, `source_hamilt`) and called from `esolver` as a named + step. +2. Do not add ad-hoc function names to `esolver`. New steps must reuse the + naming conventions already shared across solvers, so that all `esolver` + implementations read uniformly. If no suitable name exists, propose the + convention change first.