clinical-trial-design: Instructions file for Claude Code

AGENTS.md — codebase tour for AI agent contributors

If you are an AI agent (Claude, GPT, Gemini, an openclaw subagent, an opencode workflow, etc.) reading this because a user has asked you to contribute to clinical-trial-design, this is your entry point. It explains the codebase the way a senior contributor would walk a new colleague through it: what each layer does, where to add a new thing, which tests gate a change, and what is in-scope for an agent contribution versus what needs a human reviewer.

For human contributors, CONTRIBUTING.md is the shorter human-facing guide; it points back here for the technical detail. The strategic why behind the project's direction is described in the public README.md and CHANGELOG.md.

What clinical-trial-design is

An end-to-end clinical-trial-design assistant exposed as a Claude Code plugin, covering Phase 2 and Phase 3 confirmatory designs. It wraps the established R packages gsDesign, gsDesign2, and (selectively) rpact and simtrial behind a stable JSON schema, exposes those wrappers as MCP tools, and ships a skill prompt that orients the host LLM. The project's value comes from four properties:

1. Coverage. 13 design tools spanning fixed and group-sequential designs across binary / continuous / TTE-PH / TTE-NPH families, with superiority / non-inferiority / equivalence as a parameter (not a separate tool).
2. Verification. verify_design() Monte Carlo gate (±2 pp power, ±0.5 pp Type I) cross-checks every design before it is returned as final.
3. Reproducibility. A 176-case benchmark corpus with machine-readable YAML cases anchored to FDA / ICH / published trials.
4. Statelessness. No persistence, no telemetry, no outbound network calls (CI-enforced — see SECURITY.md).

Repo layout

clinical-trial-design/
├── .claude-plugin/        # Claude Code plugin manifest + marketplace.json
├── .github/
│   ├── ISSUE_TEMPLATE/    # Per-task templates an agent can fill programmatically
│   └── workflows/         # CI: testthat, smoke matrix, security-grep gate
├── AGENTS.md              # ← you are here
├── CONTRIBUTING.md        # human-facing contributor guide
├── SECURITY.md            # statelessness guarantees + reporting
├── HOSTING.md             # recommended host configurations
├── CHANGELOG.md           # release-by-release history
├── README.md              # quickstart + tool surface + tested versions
├── benchmarks/            # 176-case YAML corpus + JSON schema
│   ├── schema/design.schema.json
│   ├── README.md, GLOSSARY.md, ROADMAP.md
│   └── <family>/cases/<id>.yaml + <id>.md
├── docs/
├── mcp-server/            # TypeScript MCP server (stdio transport)
│   ├── src/
│   │   ├── index.ts       # registers all 13 tools, runs stdio
│   │   ├── r-bridge.ts    # spawns Rscript per call, JSON roundtrip
│   │   └── tools/<tool-name>.ts   # one zod schema + register() per tool
│   ├── dist/index.js      # bundled (esbuild) — committed; ships in plugin
│   ├── scripts/smoke.mjs  # 13-case smoke matrix
│   └── package.json
├── r-package/ClinicalTrialDesign/  # R package
│   ├── DESCRIPTION, NAMESPACE
│   ├── R/                 # one file per design wrapper + utils + cli + dispatcher
│   ├── inst/launcher.R    # sources R/ in-place; invoked by mcp-server/r-bridge
│   └── tests/testthat/    # one test file per design family
└── skills/clinical-trial-design/SKILL.md  # skill prompt that orients the host LLM