Merge pull request #1029 from pharmaverse/1028-feat/ai-knowledge

feat: add AGENTS.md for AI agent workflow (#1028)

Author: Shaakon35

.Rbuildignore

@@ -4,6 +4,7 @@
 ^\.Rproj\.user$
 ^\.renvignore$
 ^CONTRIBUTING.md$
+^AGENTS\.md$
 ^pkgdown/
 ^dev/
 ^\.lintr$

.github/agents/anca-developer.agent.md

@@ -0,0 +1,38 @@
+---
+name: anca-developer
+description: aNCA R package and Shiny app development specialist. Handles code changes, refactoring, documentation, and test writing following pharmaverse conventions.
+---
+
+You are an R package development specialist for the aNCA project (automated Non-Compartmental Analysis).
+
+## Capabilities
+
+- Edit R package code in `R/` following roxygen2 and namespace conventions
+- Edit Shiny modules in `inst/shiny/` following module communication patterns
+- Write tests in `tests/testthat/` using `describe`/`it` with value-level assertions
+- Update roxygen2 documentation (`@param`, `@returns`, `@export`)
+- Refactor and rename functions across the codebase
+- Trace data flow through Shiny modules
+
+## Constraints
+
+- Cannot run R code (`devtools::document()`, `devtools::test()`, `devtools::check()`)
+- Cannot run or visually debug the Shiny app
+- Cannot approve PRs or merge branches
+- Always use `pkg::function()` syntax for external calls
+- Never use `library()` or `require()` in package code
+- Never edit `man/` or `NAMESPACE` files manually
+
+## Workflow
+
+1. Read relevant files to understand context before editing
+2. Follow existing code patterns and conventions
+3. Make targeted changes — avoid unrelated modifications
+4. Suggest running `devtools::document()` and `devtools::test()` after changes
+5. Flag anything that needs manual testing (Shiny UI, interactive features)
+
+## References
+
+- `AGENTS.md` — Full development guidelines
+- `.github/copilot-instructions.md` — Repository-wide conventions
+- `.github/instructions/` — Path-specific coding rules

.github/agents/pr-reviewer.agent.md

@@ -0,0 +1,40 @@
+---
+name: pr-reviewer
+description: Reviews pull requests for the aNCA R package. Checks code style, missing tests, documentation gaps, and convention violations.
+---
+
+You are a PR reviewer for the aNCA project.
+
+## Review Process
+
+1. Read the PR diff and title/description
+2. Check CI status and test results
+3. Identify issues by severity:
+   - **Error**: Bugs, broken logic, missing required elements
+   - **Warning**: Missing tests, documentation gaps, convention violations
+   - **Info**: Suggestions for improvement
+
+## What to Check
+
+- All exported functions have roxygen2 docs (`@param`, `@returns`, `@export`)
+- External calls use `pkg::function()` syntax (no `library()` or `require()`)
+- New logic has corresponding tests in `tests/testthat/`
+- NSE column references are declared in `R/zzz.R` (alphabetically sorted)
+- `NEWS.md` is updated for user-facing changes
+- Package version is bumped in `DESCRIPTION`
+- No manual edits to `man/` or `NAMESPACE`
+
+## What NOT to Flag
+
+- Minor stylistic nitpicks (whitespace, trailing commas) that don't affect readability
+- CI/CD failure status (user can see this themselves)
+- Changes merged from main that aren't part of the PR
+
+## Output Format
+
+List findings with severity, file path, and actionable description. Do not post comments on the PR unless explicitly asked.
+
+## References
+
+- `AGENTS.md` — Full development guidelines
+- `.github/PULL_REQUEST_TEMPLATE.md` — PR checklist

.github/copilot-instructions.md

@@ -0,0 +1,56 @@
+# aNCA — Copilot Instructions
+
+This is an R package for automated Non-Compartmental Analysis (NCA) with a Shiny app interface.
+
+## Repository Structure
+
+- `R/` — Package R functions (exported)
+- `inst/shiny/` — Shiny application code
+- `tests/testthat/` — Unit tests
+- `man/` — Documentation (auto-generated, do not edit)
+- `data/` — Package data
+
+## Key Constraints
+
+- No `library()` or `require()` in package code under `R/`
+- Use `pkg::function()` syntax for all external function calls
+- All exported functions must have roxygen2 docs (`@param`, `@returns`, `@export`)
+- Run `devtools::document()` after modifying roxygen comments
+- Run `devtools::test()` before committing
+
+## Dependencies
+
+- Check `DESCRIPTION` Imports before using any package
+- For new dependencies: `usethis::use_package("pkg")`
+- Use explicit namespaces: `dplyr::filter(x > 0)` not `filter(x > 0)`
+
+## Testing
+
+- Test file names match source: `R/foo.R` → `tests/testthat/test-foo.R`
+- Use `describe` and `it` functions
+- Include value-level assertions, not just structure checks
+- Use test data from `tests/testthat/setup.R` where appropriate
+
+## Anti-patterns
+
+- Do not edit `man/` or `NAMESPACE` files manually
+- Do not add unused `globalVariables` to `R/zzz.R`
+- Do not push without running `devtools::document()` first
+- Do not skip tests or lintr checks
+
+## PR Workflow
+
+- Branch name: `<issue-number>-<type>/<short-description>`
+- Before submitting: bump version, update NEWS.md
+- Link issue with `Closes #<number>` in PR description
+- Add at least 2 core team reviewers (from DESCRIPTION)
+
+## CI Checks
+
+All PRs must pass: lintr, unit tests, test coverage, man page generation, and spell check.
+
+## Additional Context
+
+See `AGENTS.md` for full development guidelines.
+See `.github/instructions/` for path-specific coding conventions.
+See `.github/skills/` for reusable agent workflows.

.github/instructions/r-code.instructions.md

@@ -0,0 +1,58 @@
+---
+applyTo: "R/**/*.R"
+---
+
+# R Package Code
+
+## File naming
+
+- One main function per file: `R/my_function.R`
+- Match file name to function: `positive_mean()` → `positive_mean.R`
+- Utilities: `R/utils.R` for small helpers
+
+## Dependencies
+
+- Check `DESCRIPTION` Imports before using any package
+- For new dependencies: `usethis::use_package("pkg")`
+- Use explicit namespaces in code: `dplyr::filter(x > 0)` not `filter(x > 0)`
+- No `library()` or `require()` in package code
+
+## Documentation (roxygen2)
+
+All exported functions must have `@param`, `@returns`, and `@export`:
+
+```r
+#' Calculate mean of positive values
+#'
+#' @param x A numeric vector.
+#' @param na.rm Logical. Remove NA values? Default `TRUE`.
+#'
+#' @returns A single numeric value.
+#' @export
+#'
+#' @examples
+#' positive_mean(c(-1, 2, 3, NA))
+positive_mean <- function(x, na.rm = TRUE) {
+  x <- x[x > 0]
+  mean(x, na.rm = na.rm)
+}
+```
+
+Run `devtools::document()` after modifying roxygen comments.
+
+## Global variables (`R/zzz.R`)
+
+Use for non-standard evaluation (NSE) column references:
+
+```r
+utils::globalVariables(c("DOSEA", "TRT01A", "GROUP"))
+```
+
+- Only for code in `R/`, not in `inst/shiny/`
+- Keep alphabetically sorted, no duplicates
+
+## Anti-patterns
+
+- Do not edit `man/` or `NAMESPACE` files manually
+- Do not add unused globalVariables to `R/zzz.R`
+- Do not push without running `devtools::document()` first

.github/instructions/shiny.instructions.md

@@ -0,0 +1,36 @@
+---
+applyTo: "inst/shiny/**"
+---
+
+# Shiny App Code
+
+## Module communication
+
+- `session$userData$results` — computed results (CDISC datasets, NCA results)
+- `session$userData$project_name()` — reactive, auto-populated from STUDYID
+- `session$userData$slope_rules()` — reactive (non-nested)
+- Data flows: `data_upload_server` → `adnca_raw` → `tab_data_server` → `tab_nca_server`
+
+## Export / ZIP (`tab_nca/zip.R`)
+
+- `TREE_LIST` defines export structure
+- `input$res_tree` returns selected items as text names
+- Zip filename: `ProjectName.zip` or fallback `NCA_STUDYID.zip`
+- Pre-Specs sheets auto-generated from CDISC data, filtered to exported variables
+
+## Exploration plots
+
+- Default color_by priority: `DOSEA > TRT01A > GROUP > ACTARM > COHORT`
+- Default facet_by priority: `TRT01A > DOSEA > GROUP > ACTARM > COHORT`
+- Auto-mapping includes: `COHORT`, `PART`, `PERIOD`
+
+## CSS caveat
+
+`inst/shiny/www/main.css` has `--_sidebar-width: 170px !important`
+
+To change sidebar width, modify the CSS variable, not the R parameter.
+
+## Anti-patterns
+
+- Do not add `globalVariables` here; place them only in `R/zzz.R`
+- Agents cannot run or visually debug the Shiny app; test UI changes manually

.github/instructions/tests.instructions.md

@@ -0,0 +1,55 @@
+---
+applyTo: "tests/**"
+---
+
+# Testing
+
+## File structure
+
+- Test file names match source: `R/foo.R` → `tests/testthat/test-foo.R`
+- Use `describe` and `it` functions
+- Include value-level assertions, not just structure checks
+- Use the test data created in `tests/testthat/setup.R` where appropriate
+
+## Example
+
+```r
+describe("g_lineplot: structure and arguments", {
+  it("returns a ggplot object with individual labels", {
+    p <- g_lineplot(
+      data = ind_data,
+      x_var = "time_var",
+      y_var = "AVAL",
+      x_unit = "RRLTU",
+      y_unit = "AVALU",
+      color_by = "USUBJID"
+    )
+    expect_s3_class(p, "ggplot")
+    expect_equal(p$labels$title, "PK Concentration - Time Profile")
+    expect_equal(p$labels$y, "Concentration [ng/mL]")
+    expect_equal(p$labels$x, "Time [hours]")
+    expect_equal(p$labels$colour, "USUBJID")
+  })
+
+  it("applies faceting", {
+    p <- g_lineplot(
+      data = ind_data,
+      x_var = "time_var",
+      y_var = "AVAL",
+      color_by = "USUBJID",
+      facet_by = "PARAM"
+    )
+    expect_s3_class(p$facet, "FacetWrap")
+  })
+})
+```
+
+## CI Checks
+
+All PRs must pass:
+
+- Code passes lintr checks
+- Code passes all unit tests
+- New logic covered by unit tests
+
+Run tests with: `devtools::test()`