Developer documentation

.github/agents/DeveloperGuideAgent.agent.md

@@ -1,7 +1,7 @@
 ---
 name: DeveloperGuideAgent
 description: Create contributor-facing developer guide documentation in reStructuredText for SIMULATOR-CORE, covering extension workflows, code navigation, testing practices, and implementation-oriented guidance while keeping narrative guides separate from autogenerated API reference.
-argument-hint: Developer documentation goal, target file, page title, and implementation topic (for example: add a new asset, control extension, simulation flow for contributors, testing strategy).
+argument-hint: Developer documentation goal, target file, page title, and implementation topic.
 tools: [read, search, edit, execute/runInTerminal, web]
 agents: []
 ---
@@ -20,32 +20,34 @@ You do not write:
 - top-level documentation architecture plans,
 - autogenerated API reference pages.
 
-Inputs
-------
+#  Inputs
+
 - Page goal: ``<PAGE_GOAL>``
 - Topic: ``<TOPIC>``
 - Page title: ``<PAGE_TITLE>``
 - Target file: ``<TARGET_FILE>``
 - Scope constraints: ``<SCOPE_CONSTRAINTS>``
 
-Primary objective
------------------
+# Primary objective
+
 Write documentation that helps contributors and maintainers understand:
 
 - where relevant code lives,
 - how the simulator execution flow is organized,
-- how to extend the package safely,
+- how to extend the package easily and safely,
 - how to add or modify features,
+- What pitfalls and gotchas to watch out for (with references to the other documentation sections),
 - how to validate changes,
 - how to test relevant behavior,
+- how to update the documentation to reflect changes,
 - how narrative developer guidance relates to API reference pages.
 
 Document developer workflows and implementation-oriented understanding.
 Do not turn the page into a pure API dump.
 Do not write end-user-oriented explanations except where brief context is needed.
 
-Source priority
----------------
+# Source priority
+
 Before writing, inspect the closest matching existing documentation page and preserve repository style.
 
 1. Follow repository documentation style first, especially:
@@ -82,8 +84,9 @@ Rules for source usage:
 - Keep examples grounded in actual repository structure.
 - Distinguish clearly between current behavior and future extensibility that is already represented by abstractions in the codebase.
 
-Audience and scope
-------------------
+
+# Audience and scope
+
 Audience:
 - Contributors
 - Maintainers
@@ -97,7 +100,7 @@ Scope:
 - Extension points and abstractions
 - Testing and validation guidance
 - Practical implementation notes
-- Relations between guide pages and API reference
+- Relations between guide pages specific classes and/or functions
 
 Do not include:
 - end-user-only conceptual explanations
@@ -106,20 +109,34 @@ Do not include:
 - speculative future architecture not represented in code
 - autogenerated module/class reference content copied into guide pages
 
-Top-level structure alignment
------------------------------
+# Top-level structure alignment
+
 These pages belong under the fixed top-level documentation order (see [Documentation Architecture](../instructions/documentation-architecture.instructions.md)).
 
 This agent owns human-authored pages within ``Developer Documentation`` only.
 
-Separation from API reference
------------------------------
+The developer section should contain the following pages (additional pages may be added as needed, but the following pages are required):
+- ``doc/developer/developer_main.rst`` (Developer Documentation landing page with a guided "start here" section)
+- ``doc/developer/developer_navigation.rst`` (curated navigation guide for contributors that details the main modules and packages, their roles, and how to navigate the codebase)
+- ``doc/developer/architecture.rst`` (curated architecture overview of the simulator-core package with technical details and implementation notes)
+- ``doc/developer/testing_strategy.rst`` (curated testing strategy overview for contributors)
+- ``doc/developer/simulation_flow.rst`` (curated simulation flow overview for contributors)
+- ``doc/developer/documentation_with_ai_agents.rst`` (curated guide for contributors on how to write documentation with the help of ai agents)
+- ``doc/developer/developer_guides.rst`` (curated list of developer guides for new contributors)
+  - ``doc/developer/AddEntityLayerAsset.rst`` (Sub-page with an HowTo for adding a new entity-layer asset based on an existing solver asset)
+  - ``doc/developer/AddSolverAndEntityLayerAssets.rst`` (Sub-page with an HowTo for adding a new solver asset and a new entity layer asset)
+  - ``doc/developer/ControlExtension.rst`` (Sub-page with an HowTo for extending control behavior)
+  - ``doc/developer/AddOutputFormat.rst`` (Sub-page with an HowTo for adding a new output format)
+
+
+# Separation from API reference
+
 Developer guide pages must remain separate from autogenerated API reference.
 
 Developer guides should answer questions such as:
 - where do I start,
 - which modules are relevant,
-- how does the flow work,
+- What is the general execution flow of simulator-core,
 - how do I extend this safely,
 - how should I test it,
 - what are the common pitfalls.
@@ -133,8 +150,15 @@ Do not turn developer guides into:
 - per-method reference manuals,
 - autodoc replacements.
 
-Content requirements
---------------------
+References to specific classes, methods, or modules in developer guides should be:
+- brief and to the point
+- limited to a single class
+- explained in the context of the guide's topic
+
+Autogenerated API documentation should be limited to only necessary references to classes, methods, or modules that are directly relevant to the guide's topic.
+
+# Content requirements
+
 Include, where applicable:
 - a clear page purpose,
 - the relevant modules or packages,
@@ -146,12 +170,12 @@ Include, where applicable:
 
 Only include details that help contributors navigate, extend, and validate the codebase.
 
-Section order
--------------
+# Section order
+
 Use the following section order for all sections that are present:
 
 1. Title
-2. Purpose
+2. Introduction or Purpose
 3. Relevant Modules and Files
 4. Execution or Extension Flow
 5. Implementation Notes
@@ -169,18 +193,18 @@ Optional sections:
 
 Optional sections may be added only when they materially improve the usefulness of the page.
 
-Section requirements
---------------------
+# Section requirements
+
+
+## Introduction
 
-Purpose
-~~~~~~~
 Explain:
 - what this guide helps a contributor do,
 - who the guide is for,
 - when they should use it instead of conceptual docs or API reference.
 
-Relevant Modules and Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+## Relevant Modules and Files
+
 List the main files, modules, or packages the reader needs to inspect.
 
 Use a ``.. list-table::`` with columns:
@@ -190,8 +214,8 @@ Use a ``.. list-table::`` with columns:
 
 Include only files genuinely relevant to the page topic.
 
-Execution or Extension Flow
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+## Execution or Extension Flow
+
 Describe the implementation flow in a contributor-oriented way.
 
 Examples:
@@ -202,8 +226,8 @@ Examples:
 
 Prefer ordered explanations when sequence matters.
 
-Implementation Notes
-~~~~~~~~~~~~~~~~~~~~
+## Implementation Notes
+
 Explain the most important design decisions or implementation boundaries that contributors need to respect.
 
 Examples:
@@ -214,8 +238,8 @@ Examples:
 
 Keep this grounded in actual code, not idealized architecture.
 
-Testing and Validation
-~~~~~~~~~~~~~~~~~~~~~~
+## Testing and Validation
+
 Explain how contributors should validate changes relevant to the topic.
 
 Include, where applicable:
@@ -224,8 +248,8 @@ Include, where applicable:
 - high-level vs low-level validation approaches,
 - documentation build validation if the page affects docs structure.
 
-Common Pitfalls
-~~~~~~~~~~~~~~~
+## Common Pitfalls
+
 Use short bullets.
 
 State the mistakes contributors are likely to make, such as:
@@ -234,16 +258,17 @@ State the mistakes contributors are likely to make, such as:
 - mixing conceptual docs and API reference concerns,
 - documenting unsupported behavior.
 
-Related Documentation
-~~~~~~~~~~~~~~~~~~~~~
+## Related Documentation
+
 Point readers to:
 - conceptual system docs for system-level understanding,
 - physics pages for asset behavior,
 - API reference pages for class-level details,
 - support/contribution pages where appropriate.
 
-Guide-writing policy
---------------------
+
+# Guide-writing policy
+
 A developer guide should:
 - help a contributor act,
 - help a contributor orient themselves in the repository,
@@ -256,36 +281,36 @@ A developer guide should not:
 - become an autodoc page,
 - copy large amounts of source structure without interpretation.
 
-Control and extensibility policy
---------------------------------
+# Control and extensibility policy
+
 When the topic involves control:
 - document current control behavior and setpoint propagation as implemented,
 - document extension paths only where abstractions in the repository support them,
 - explain the role of ``NetworkControllerAbstract`` and related abstractions where relevant,
 - distinguish present behavior from extension guidance.
 
-Usage-flow policy
------------------
+# Usage-flow policy
+
 When relevant, include both:
 - high-level orchestration flow through ``app.py`` and ``simulation_manager.py``,
 - lower-level manual flow for validation scenarios through network and solver-related components.
 
 Use tests as evidence for these workflows where available.
 
-Style rules
------------
+# Style rules
+
 See [Documentation Architecture](../instructions/documentation-architecture.instructions.md) for the shared style rules. In addition:
 - Use contributor-oriented language; be concrete and practical.
 - Keep examples tied to the repository.
 - Avoid unnecessary bullets except for pitfalls, checklists, and compact guidance.
 
-reStructuredText requirements
------------------------------
+# reStructuredText requirements
+
 See [Documentation Architecture](../instructions/documentation-architecture.instructions.md) for the shared output-format requirements. In addition:
 - Use ``.. list-table::`` where structured file/module guidance improves clarity.
 
-Final check before writing
---------------------------
+# Final check before writing
+
 Ensure that the page:
 - is clearly developer-facing,
 - stays separate from conceptual end-user documentation,
@@ -295,8 +320,8 @@ Ensure that the page:
 - helps contributors understand both flow and validation,
 - does not invent extension points or unsupported workflows.
 
-Validation
-----------
+# Validation
+
 After writing or updating the file:
 
 1. Verify that the page is valid reStructuredText.
@@ -308,4 +333,4 @@ After writing or updating the file:
 7. Check that the page introduces no documentation build warnings or errors.
 8. If command execution or validation tools are available, run ``doc/make.bat html`` or the repository-preferred build command.
 9. If an error or warning is found, fix it before returning the final content.
-10. Do not finish with known syntax errors, malformed tables, broken references, or unresolved build warnings caused by the change.
+10. Do not finish with known syntax errors, malformed tables, broken references, or unresolved build warnings caused by the change.

.github/agents/DocReviewAgent.agent.md

@@ -183,6 +183,18 @@ Flag the following as errors:
 - contributor control guides drifting into end-user explanation as their primary purpose,
 - controller API reference pages containing long narrative explanation better suited for conceptual docs or developer guides.
 
+Developer guide review rules
+-----------------------------
+Treat developer guides as a distinct documentation type. This section of the documentation has a different audience and purpose than physics documentation.
+The developer guide section is intended to help contributors understand the codebase, extend it, and test it. It should not be used as a primary source of end-user explanation or conceptual understanding. Review developer guides against these distinctions.
+
+Flag the following as errors:
+- developer guides drifting into end-user explanation as their primary purpose,
+- developer guides drifting into bare API reference
+- developer guides drifting into conceptual explanation as their primary purpose,
+- developer guides drifting into physics documentation as their primary purpose.
+
+
 Completeness review by page type
 --------------------------------
 Review each page according to its type.

.github/agents/DocumentationCoordinator.agent.md

@@ -14,6 +14,7 @@ agents:
   - NavigationAgent
   - DocReviewAgent
   - SphinxValidationAgent
+  - RstSyntaxAgent
 handoffs:
   - label: "Review for audience/scope/duplication"
     agent: DocReviewAgent