AGENTS.md

Written for version 0.1.14. Part of Rules for working, which lists the sources.

What it is. The rules for working in the repository, for everyone: the people on the project and any AI agents working for them. It covers conventions, data handling and checks. It opens by dividing the documentation into four places, each covering its own topic without repeating the others:

Where	Covers
analysis-plan.md	What the analysis is meant to do
ARCHITECTURE.md	How the code is built: scripts, data flow, and the objects passed between them
AGENTS.md	How to work in the repository: rules, conventions and checks
GitHub Issues	Open scientific decisions (decision issues), gaps between code and plan, and known defects

Where it lives. At the top of the repository. The project website shows it on a page that only includes the root file, so you edit the root file, never the page.

What’s in it. The plugin’s template has these sections. Parts in angle brackets are filled in for each project.

• The project. One paragraph on the question and the data. Then the standing rules: the analysis plan is the source of truth, and code that needs to depart from it goes to a decision issue first. The deciders are named here with their areas; anyone may add to a decision issue, but only a decider settles it. It also says this is an analysis, not an R package, and names the default branch (the main version of the project). That branch is protected: changes reach it only through pull requests (proposed changes that others can review before they are merged).
• Data sources and what agents may do. A table with one row per data source the analysis uses: the source, the package that loads it, the package’s documentation, whether the team maintains that package or it is external, how access is restricted, and what AI agents may do with it. Code that touches a source goes through its package. For a restricted source, the agents’ column starts at “None: code, documentation and synthetic data only”. Only a person can widen it, through a pull request that names the agreement and section that permit it, the approved AI service, and exactly what agents may do. Agents never propose this change, and nothing in personal instructions can grant it. The template then splits the rules: problems in a package the team maintains are fixed or reported in that package; problems in an external package are worked around in the project’s own code, and whether to report them upstream is the person’s call.
• Exploration and definitive analysis. Exploring on a branch or fork is welcome, and its findings are labelled preliminary. A script joins the definitive analysis when R/main.R runs it; from then on every rule applies.
• Scripts and labels. R/main.R runs everything in order. Each script does one job and starts with a short header saying what it needs and what it makes. Settings a reader might want to change (a window, a year, a threshold) are named once in R/setup.R. Scripts are divided into labelled sections, marked with a comment line like ## ---- compute-summary, so the website can show the real code. Labels are unique across all scripts, because a repeated label silently shows the wrong code. Analysis variables carry readable labels, with units and time windows. No script, comment, commit message, issue or pull request contains results from restricted data unless they are cleared for release.
• Website. The site explains the code and never runs the analysis. It lists the page layout, the colour and icon for each kind of page, and the yellow highlight for content an open decision could change. It records the project’s publishing route: either the rendered docs/ folder is committed and served by GitHub Pages, or a GitHub Actions workflow renders and publishes the site. A new definitive script gets its page in the same pull request.
• Outputs. Tables and figures are written to tables/ and figures/. The project states whether they are tracked or kept out of Git until a named review clears them, and if they are kept out, whether that is because of restricted data or only publication timing. Published figures need alt text.
• Restricted data. These rules apply to everyone. Data and anything derived from patient-level records are never committed. AI agents never open restricted data, or outputs from it that are not yet cleared; anything an agent opens is sent to the model provider. Agents write and test code on synthetic data: made-up data built in code and labelled as such. Real results come from an authorized person. The section also holds the agreement’s small-cell rule and the rules for keys, tokens and paid services.
• Coding conventions. The participant flow (the cohort and its STROBE diagram) comes from one piece of code using the flowchart package. Code lists are checked against the official code sets, and joins are checked so rows don’t multiply. Package functions are checked against their documentation rather than written from memory. The style is meant to be readable by a clinician-analyst who learned R from online guides.
• Checks for any change. A checklist to run before opening a pull request: does the change follow the plan and leave open decisions open; are the cohort counts reproducible; is ARCHITECTURE.md current; does any site page run analysis code; could anything changed reveal restricted data; does main.R run in a fresh session? A project adds checks its own design needs.
• Working with agents. Each person sets their agent’s working style in their own instructions; without one, the agent works step by step. At most, an agent edits code and documents, runs code and renders the site on synthetic data, commits to a branch and opens a pull request. Under any style, an agent never merges a pull request, never chooses among the options in a decision issue, asks before running the full pipeline or expensive calls, and shows a person the exact text before posting anything as them, unless that person’s own instructions say otherwise.

Who edits it. Anyone, through a pull request. Widening what agents may do with a restricted source is a person’s change, made as described above.

What the assistant does with it. It reads AGENTS.md, the plan and ARCHITECTURE.md before making changes. During setup it adapts the template to the project. It fills the data sources table from the code that actually loads the data, not from memory, and asks about any source whose package or access terms are unclear. It asks who the deciders are, and if materials such as an IRB protocol name investigators, suggests them for the person to confirm. If no one is named yet, the line stays marked as still to fill, and decision issues can be drafted but not settled.