Building AI-Powered Development Tools: How AGENTS.md and Admiral Are Reshaping Programming Workflows

Introduction

AI coding assistants have quietly become part of the clinical R programmer's daily toolkit — autocompleting functions, suggesting test cases, drafting derivations. But these agents ship with a significant blind spot: they know nothing about ADaM conventions, CDISC standards, or how the pharmaverse ecosystem is structured. They don't know that analysis flag variables like ANL01FL take "Y" or NA — never "N". They don't know that {pharmaversesdtm} is the canonical source of test SDTM data, or that {xportr} sits downstream, ready to convert your dataset into a submission-ready XPT file. AGENTS.md is a simple, open standard designed to close that gap — and the {admiral} ecosystem now has infrastructure to generate and maintain these files automatically across every package in the family.

What Is AGENTS.md?

AGENTS.md is a plain markdown file committed to your repository that gives AI coding agents the context they need to work correctly in your project. Think of it as a README written for agents: while README.md orients a new developer to what a project is, AGENTS.md tells an AI assistant how to work within it properly.

The format is supported across a growing roster of AI coding tools — OpenAI Codex, GitHub Copilot, Google's Jules, Cursor, Aider, Gemini CLI, and more. One version-controlled file, committed alongside your code, works across all of them.

Why This Matters for the pharmaverse

ADaM derivations encode decades of CDISC regulatory expectations that simply don't surface in R syntax. The derivation logic behind ANL01FL, the specific imputation rules governing DTYPE = "LLOQ" records — none of this is inferable from code alone. It exists in standards documents, institutional knowledge, and reviewer expectations.

{admiral} also doesn't operate in isolation. It sits within a pipeline that flows from {pharmaversesdtm} test data through admiral derivations, often guided by {metacore} specifications, and ultimately out through {xportr} to submission-ready XPT files. An agent writing admiral code without that pipeline context is like a new programmer who knows only the function they're editing — not the system it belongs to.

An AGENTS.md file in an admiral-family repository can communicate all of this before the agent writes a single line of code.

A First Step in the pharmaverse AI Strategy

The {admiral} team is actively working through how to formalize its approach to AI-assisted development — which tools to encourage, what guardrails to put in place, and how to document AI's role in the programming workflow. That conversation is still early, and deliberately so: the consensus is to build real-world experience before locking in formal guidance.

That experience is already arriving, and fast.

March 7, 2026 — the question arrives. PR #2996 landed from a new contributor, maxthecat2024, fixing poorly formatted warning messages in derive_param_computed(). The PR was thorough and well-structured — detailed before/after examples, snapshot test conversions, a fully completed checklist. It was also the kind of contribution that made the team wonder: was this AI-assisted? No one knew for certain, and ultimately it didn't matter — the code was solid and it got merged. But the question itself was telling.

March 17, 2026 — the reality arrives. PR #3010 was opened not by a human contributor, but by GitHub Copilot itself — the branch named copilot/enhance-examples-derive-vars-merged-summary, the author listed as Copilot. The PR enhanced documentation examples for derive_vars_merged_summary(), correctly picking up the admiral-specific @examplesx structured example pattern from the existing codebase — context drawn directly from AGENTS.md.

But the PR also revealed an important limitation. Rather than running devtools::document() to regenerate the .Rd file, Copilot edited man/derive_vars_merged_summary.Rd directly — and its own PR description acknowledged this: "Manually updated to match roxygen2::roxygenize() output." When a reviewer flagged the issue, Copilot responded candidly: "R is not available in my sandbox environment, so I can't execute devtools::document() directly. For future sessions, I understand the correct workflow." A human reviewer ran devtools::document() outside the sandbox and pushed the correctly generated .Rd file in commit c855860.

This is an important nuance. The problem wasn't unclear instructions in AGENTS.md — it was that Copilot's execution environment simply didn't have R available. No instruction, however precise, can make an agent run a command it physically cannot execute. AGENTS.md can teach an agent the correct workflow; ensuring the environment actually supports that workflow is a separate, human-owned responsibility. That distinction matters as the community shapes its AI strategy.

This two-week window tells the whole story. AI-assisted contributions are already reaching the {admiral} repository. AGENTS.md is already helping agents navigate project-specific conventions. And the gaps it exposes are already driving improvements. This is exactly the feedback loop the community needs — not speculation about AI, but evidence from it.

AGENTS.md is the first tangible infrastructure to emerge from that thinking. Whether a contributor is a human using an AI assistant, an autonomous agent, or something in between, the code still needs to follow ADaM conventions and pharmaverse standards. AGENTS.md helps ensure it does.

If you have thoughts on what the broader strategy should look like, the discussion is open — join the conversation at admiraldev issue #547. The broader scientific open-source community is working through similar questions: rOpenSci recently published an AI policy worth reading as a reference point for how these norms are taking shape. Notably, rOpenSci's policy calls out agents.md directly in its software review submission template:

"If your repository includes an 'agents.md' file or equivalent, please provide a link, and describe how this has been used in the development of your package."

The fact that the broader scientific open-source community is already asking for AGENTS.md as part of peer review is a strong signal that this norm is catching on quickly.

The Admiral Ecosystem Implementation

Rather than each package maintaining its own file by hand, the generation logic is centralized in {admiralci}, delivering a consistent, up-to-date file to every package that opts in. The workflow assembles content from several sources:

• Programming strategy and unit testing guidelines from {admiraldev}
• Package-specific context from a YAML file in each repository (therapeutic area, related packages, relevant CDISC IGs)
• Ecosystem context describing how admiral-family packages fit into the broader pharmaverse pipeline
• ADaM fundamentals covering key variable conventions and controlled terminology patterns

The {admiral} AGENTS.md is substantial — over 1,300 lines of auto-generated context drawn directly from the {admiraldev} programming strategy, git usage, and R CMD check vignettes. It also includes a built-in verification mechanism: agents are instructed to add the comment # admiral guidelines loaded to the first line of every new R file they create, confirming that the guidelines were actually read. It's a small but clever way to make agent compliance visible during code review.

Here's a simplified illustration of the kind of content the file contains:

# AGENTS.md — admiral
## Package Overview
{admiral} provides a toolbox for ADaM dataset construction in R,
following CDISC ADaM standards and pharmaverse conventions.
## ADaM Conventions
- Flag variables (ANL01FL, SAFFL, etc.) take values "Y" or NA
- PARAM/PARAMCD pairs must align with CDISC controlled terminology
- ASEQ must be derived as the last step before dataset finalization
## Ecosystem Context
- Test SDTM data: use {pharmaversesdtm} (CDISC pilot data)
- Downstream: datasets consumed by {xportr} for XPT transport files
- Metadata: {metacore}/{metatools} provide spec-driven variable control
## Unit Testing
- Use {testthat} with expect_dfs_equal() for dataset comparisons
- Every new function requires tests for typical use, edge cases, and errors
## Documentation
- Run devtools::document() to regenerate .Rd files — never edit man/ directly
- Update NEWS.md for any user-facing function changes

One practical note: placing AGENTS.md at the repository root triggers a NOTE in R CMD check, so the file is added to .Rbuildignore. It also lives in tests/testthat/, where testing-specific guidance is scoped closest to where it's needed. Extension packages like {admiralonco}, {admiralvaccine}, and {admiralpeds} can layer their own context on top, adding therapeutic area-specific conventions without duplicating shared infrastructure content.

How to Adopt This in Your Package

Maintainers of admiral-family packages can adopt this workflow in three steps:

1. Add a YAML configuration file to your repository containing package-specific context — therapeutic area, related packages, and relevant CDISC implementation guides.
2. Reference the reusable workflow from {admiralci} in your .github/workflows/ directory.
3. Add ^AGENTS\.md$ to your .Rbuildignore.

Once configured, the workflow runs on a schedule: it pulls the latest shared content from {admiraldev}, merges it with your package's YAML, and automatically commits an updated AGENTS.md to your repository — no manual intervention required.

@online{dickinson2026,
author = {Dickinson, Jeff},
title = {AGENTS.md, \{Admiral\}, and the {AI-Assisted} {Programmer}},
date = {2026-03-31},
url = {https://pharmaverse.github.io/blog/posts/2026-03-31-agents-md-admiral-a/agents-md-admiral-and-the-ai-assisted-programmer.html},
langid = {en}
}