added agents.rst

Author: jaredmales

maintenance/cooling/measuring_glycol_freezing_point.rst

@@ -1,15 +1,16 @@
-Using the refractometer to measure the freezing point of ethylene glycol
-========================
+Measurement of coolant freezing point
+==========================================================================
 
-The cleanroom at LCO stocks an Extech R41 model refractometer in the cabinet (might be in a toolbox). It is in a black semi-hardshell case about the size of an eyeglasses case.
+We have and an Extech R41 model refractometer in the MagAO-X "Cooling system parts, tools, and hardware" box in the cleanroom.
+It is in a black semi-hardshell case about the size of an eyeglasses case.
 
 Usage
 ----------
 
 .. image:: figures/ExtechR41_refractometer_UserManual.png
 
-Latest measurement
-----------
+Latest measurements
+------------------------
 
 On 2026-03-21 we measured the MagAO-X instrument glycol concentration using the refractometer and found a freezing point of about -22 Celsius.
 

software/agents.rst

@@ -0,0 +1,40 @@
+Using AI Agents
+======================================
+
+AI Policy
+-----------------------
+You are encouraged to use AI to help you write code.  However, you are still responsible for the physics and engineering.  The following guidelines are intended to ensure that we write code that helps MagAO-X achieve its goals, but that we also learn about how the universe works and document what we learn.
+
+Standard Workflow
+----------------------
+You must still follow the standard workflow using feature branches, testing from your home directory, and pull-request to get reviewed before merging.
+
+AGENTS.md
+---------------------------
+At the top level of the MagAO-X repo there is a file named `AGENTS.md`_.  This file contains a set of guidelines for an AI agent to
+follow.  While `AGENTS.md`_ is supposed to be a standard name, in practice you should always remind your agent to refer to that file.
+
+.. _AGENTS.md: https://github.com/magao-x/MagAOX/blob/dev/AGENTS.md
+
+If you develop a new rule while working with AI, ask it to update `AGENTS.md`_ and include it in your feature branch.
+
+Plans
+--------------------------
+The current best practice is to use AI in planning mode.  Describe your problem and ask the AI to create a plan.  Then iterate on the
+plan as needed, keeping the planning document (see below) up to date.  Once you are happy with the plan, then have the agent implement it.
+
+Planning Documents
+~~~~~~~~~~~~~~~~~~~~~~~~~
+In the MagAO-X repo there is now a folder called `agents/plans`_.  One thing that has proven useful is to write your specifications in a
+new file there.  Then your prompt to the AI is simply to review that file, make a plan, and write out the plan to that same file.  The
+intention is that you then commit that file as part of your feature development.  The benefit to this practice will be that we now have
+a record of the engineering you did to create the feature.
+
+.. _agents/plans: https://github.com/magao-x/MagAOX/tree/dev/agents/plans
+
+Blast Radius -- Follow the Rules
+----------------------------------------
+It is incredibly easy to "change all the things", or "fix all the bugs", with AI.  AI agents are always willing to work, and often ask
+to go further if they recognize more problems.  Try to avoid this.  We consider it good engineering practice to make small focused
+changes and test them, and slowly expand.  This is why it is crucial to follow the development guidelines and our git-branch-PR workflow
+so that we can maintain some semblance of traceability and recoverability.

software/index.rst

@@ -7,6 +7,7 @@ The MagAO-X software system.
    :maxdepth: 1
 
    hacking
+   agents
    python_indi_device
 
 Links